API การตลาด

การเรียกดูข้อมูลลูกค้า

คุณสามารถอ่านข้อมูลลูกค้าได้ด้วย Webhooks หรือการอ่านครั้งละหลายรายการ

ก่อนเริ่มต้น

หากต้องการอ่านเพียงบางช่องของโฆษณา เช่น ad_id หรือ campaign_id คุณจำเป็นต้องมีสิ่งต่อไปนี้

หากต้องการอ่านข้อมูลลูกค้าและข้อมูลระดับโฆษณาทั้งหมด คุณจำเป็นต้องมีสิ่งต่อไปนี้

หมายเหตุ: หากผู้ดูแลเพจนี้ไม่เคยปรับแต่งข้อมูลลูกค้า หรือไม่ได้รับสิทธิ์การอนุญาตให้เข้าถึงจากตัวจัดการสิทธิ์การเข้าถึงข้อมูลลูกค้า ผู้ดูแลเพจทั้งหมดจะได้รับสิทธิ์การอนุญาตให้เข้าถึงข้อมูลลูกค้า หากผู้ดูแลธุรกิจปรับแต่งสิทธิ์การอนุญาตให้เข้าถึงข้อมูลลูกค้า การเข้าถึงจะขึ้นอยู่กับการกำหนดค่าของผู้ดูแลธุรกิจว่าผู้ดูแลเพจขั้นพื้นฐานจะมีสิทธิ์การอนุญาตให้เข้าถึงข้อมูลลูกค้าหรือไม่

ขีดจำกัดอัตรา

ขีดจำกัดอัตราจะเท่ากับ 200 คูณ 24 คูณด้วยจำนวนข้อมูลลูกค้าที่รวบรวมจากเพจ Facebook ในช่วง 90 วันที่ผ่านมา หากคุณเรียกใช้มากกว่านี้ภายใน 24 ชั่วโมง คำขอของคุณจะแสดงข้อผิดพลาด

กรองตามช่วงวันที่

ส่งคำขอ GET ไปยังตำแหน่งข้อมูล /ads/lead_gen/export_csv/ ที่รูปแบบวันที่เป็นประทับเวลา POSIX หรือ UNIX ดังนี้:

curl -i -X GET "https://www.facebook.com/ads/lead_gen/export_csv/
    ?id=<FORM_ID>
    &type=form
    &from_date=1482698431
    &to_date=1482784831"

ข้อควรระวัง

  • หากไม่ได้ตั้งค่า from_date หรือตั้งไว้น้อยกว่าเวลาสร้างฟอร์ม ระบบจะใช้เวลาในการสร้างฟอร์ม

  • หากไม่ได้ตั้งค่า to_date หรือตั้งไว้มากกว่าเวลาปัจจุบัน ระบบจะใช้เวลาปัจจุบัน

  • หากรายการใดไม่มี ID โฆษณาหรือ ID กลุ่มโฆษณาใน TSV อาจเกิดจากสาเหตุต่อไปนี้:

    • ข้อมูลลูกค้าสร้างจากการเข้าถึงแบบออร์แกนิก ในกรณีนี้ is_organic ใน TSV จะแสดง 1 หรือจะมีค่าเป็น 0
    • ข้อมูลลูกค้าอาจส่งมาจากภาพตัวอย่างโฆษณา
    • ผู้ขอข้อมูลลูกค้าไม่มีสิทธิ์ของผู้ลงโฆษณาในบัญชีโฆษณา

Webhooks

รับการอัพเดตแบบเรียลไทม์สำหรับโฆษณาแบบกรอกฟอร์ม

ขั้นตอนที่ 1: เริ่มต้นใช้งาน

ไปที่คู่มือเริ่มต้นใช้งาน Webhooks ของเราเพื่อตั้งค่าตำแหน่งข้อมูลและกำหนดค่า Webhook ของคุณ

ขั้นตอนที่ 2: รับโทเค็นการเข้าถึงเพจแบบระยะยาว

สร้างโทเค็นการเข้าถึงเพจแบบระยะยาวเพื่อดึงข้อมูลอย่างต่อเนื่องโดยไม่ต้องกังวลเรื่องวันหมดอายุ

ขั้นตอนที่ 3: ติดตั้งแอพของคุณบนเพจ

ไปที่คู่มือ Webhooks สำหรับเพจของเราเพื่อเรียนรู้วิธีติดตั้งแอพของคุณบนเพจ

การตอบกลับ Webhook

เมื่อสร้างการรวบรวมข้อมูลลูกค้า แอพของคุณจะได้รับการตอบกลับจาก Webhook ดังนี้

array(
  "object" => "page",
  "entry" => array(
    "0" => array(
      "id" => 153125381133,
      "time" => 1438292065,
      "changes" => array(
        "0" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123123,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        ),
        "1" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123124,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        )
      )
    )
  )
)

คุณสามารถใช้ leadgen_id เพื่อเรียกดูข้อมูลที่เชื่อมโยงกับข้อมูลลูกค้าได้

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{lead-id}/
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<LEAD_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
};
const sample_code = (new Lead(id)).get(
  fields,
  params
);
logApiCallResult('sample_code api call complete.', sample_code);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<LEAD_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
);
echo json_encode((new Lead($id))->getSelf(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<LEAD_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
}
print Lead(id).get(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<LEAD_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Lead(id, context).get()
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<LEAD_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

lead = FacebookAds::Lead.get(id ,'')
Open In Graph API Explorer

เมื่อดำเนินการสำเร็จ แอพของคุณจะได้รับการตอบกลับดังต่อไปนี้:

{
  "created_time": "2015-02-28T08:49:14+0000", 
  "id": "<LEAD_ID>", 
  "ad_id": "<AD_ID>",
  "form_id": "<FORM_ID>",
  "field_data": [{
    "name": "car_make",
    "values": [
      "Honda"
    ]
  }, 
  {
    "name": "full_name", 
    "values": [
      "Joe Example"
    ]
  }, 
  {
    "name": "email", 
    "values": [
      "joe@example.com"
    ]
  },
  {
    "name": "selected_dealer", 
    "values": [
      "99213450"
    ]
  }],
  ...
}

เรียนรู้เพิ่มเติม

คุณสามารถดูตัวอย่างการใช้งานนี้ได้ในที่จัดเก็บ Github ของเรา

การอ่านครั้งละหลายรายการ

แอพที่สร้างหลังวันที่ 2 กรกฎาคม 2018 จะถูกบังคับให้ต้องใช้สิทธิ์การอนุญาต leads_retrieval เพื่ออ่านข้อมูลลูกค้า

leads มีอยู่ทั้งในกลุ่มโฆษณาและโหนดฟอร์ม ซึ่งจะส่งกลับข้อมูลทั้งหมดที่เชื่อมโยงกับอ็อบเจ็กต์ที่เกี่ยวข้อง เนื่องจากฟอร์มสามารถนำมาใช้ใหม่ได้กับโฆษณาหลายตัว ฟอร์มของคุณจึงอาจมีข้อมูลลูกค้ามากกว่าโฆษณาที่ใช้ฟอร์มนั้นอย่างมาก

หากต้องการอ่านครั้งละหลายรายการตามโฆษณา ให้ดำเนินการดังนี้

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{adgroup-id}/leads
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_GROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
};
const leadss = (new Ad(id)).getLeads(
  fields,
  params
);
logApiCallResult('leadss api call complete.', leadss);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_GROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
);
echo json_encode((new Ad($id))->getLeads(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
}
print Ad(id).get_leads(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_GROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).getLeads()
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
leadss = ad.leads({
    fields: {  },
})
Open In Graph API Explorer

หากต้องการอ่านตามฟอร์ม ให้ดำเนินการดังนี้:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

การตอบกลับ:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

การอ่านค่าคำถามตัวค้นหาร้านค้า

คำถามตัวค้นหาร้านค้าทำงานไม่ต่างจากคำถามอื่นๆ คำถามตัวค้นหาร้านค้าจะมี ID ช่องที่จะแมปกับคำถามในระหว่างการสร้างฟอร์ม และจะถูกส่งไปเช่นเดียวกับคำถามอื่นๆ ค่าที่ส่งผ่านจะมาจากหมายเลขร้านค้าของตำแหน่งที่เลือก

ตัวอย่างเช่น หากคุณมีคำถามตัวค้นหาร้านค้าที่มี selected_dealer เป็น ID ช่อง หากต้องการดึงข้อมูลลูกค้าครั้งละหลายรายการ คุณสามารถเรียกใช้ดังต่อไปนี้ได้

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

การตอบกลับ:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
        {
          "name": "selected_dealer", 
          "values": [
            "99213450"
          ]
        }
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

การอ่านการตอบกลับข้อความจำกัดความรับผิดชอบที่กำหนดเอง

field_data ไม่มีการตอบกลับสำหรับกล่องกาเครื่องหมายข้อจำกัดความรับผิดชอบที่กำหนดเองแบบระบุหรือไม่ก็ได้ ที่ผู้ใช้อาจจะกรอก หากต้องการเรียกดูการตอบกลับ ให้ใช้ช่อง custom_disclaimer_responses

curl -X GET \
"https://graph.facebook.com/<API_VERSION>/<LEADGEN_ID>?
fields=custom_disclaimer_responses"

การตอบกลับ:

{
  "custom_disclaimer_responses": [
    {
      "checkbox_key": "optional_1",
      "is_checked": "1"
    },
    {
      "checkbox_key": "optional_2",
      "is_checked": ""
    }
  ],
  "id": "1231231231"
}

การกรองข้อมูลลูกค้า

ตัวอย่างนี้กรองข้อมูลลูกค้าตามประทับเวลา ประทับเวลาควรเป็นแบบ Unix

curl -X GET \
  -d 'filtering=[
       {
         "field": "time_created",
         "operator": "GREATER_THAN",
         "value": 1731610469
       }
     ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{adgroup-id}/leads
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_GROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'filtering' : [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
};
const leadss = (new Ad(id)).getLeads(
  fields,
  params
);
logApiCallResult('leadss api call complete.', leadss);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_GROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'filtering' => array(array('field' => 'time_created','operator' => 'GREATER_THAN','value' => 1721709809)),
);
echo json_encode((new Ad($id))->getLeads(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'filtering': [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
}
print Ad(id).get_leads(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_GROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).getLeads()
      .setParam(\"filtering\", \"[{\\"field\\":\\"time_created\\",\\"operator\\":\\"GREATER_THAN\\",\\"value\\":1721709809}]\")
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
leadss = ad.leads({
    fields: {  },
    filtering: [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
})
Open In Graph API Explorer

operator มีค่าใดค่าหนึ่งดังต่อไปนี้

ตัวดำเนินการความหมาย

LESS_THAN

ตัวกรองสำหรับค่าที่ต่ำกว่าประทับเวลา

GREATER_THAN

ตัวกรองสำหรับค่าที่มากกว่าประทับเวลา

GREATER_THAN_OR_EQUAL

ตัวกรองสำหรับค่าที่มากกว่าหรือเท่ากับประทับเวลา

การทำให้เป็นโทเค็น

หากฟอร์มมี ID ช่องที่กำหนดเอง ช่องและค่าที่ส่งกลับจะเป็นช่องและค่าที่ระบุ

แหล่งข้อมูล