檢索潛在顧客資料

您可以使用 Webhooks批量讀取來讀取潛在顧客資料。

準備工作

如要讀取廣告特定欄位(例如 ad_idcampaign_id),您需要使用以下項目:

如要讀取所有潛在顧客資料及廣告級別資料,您需要使用以下項目:

備註:如果此專頁管理員從未自訂過潛在顧客,或使用潛在顧客資料下載權限管理工具授予存取權限,則所有專頁管理員都將擁有潛在顧客資料下載權限。如果潛在顧客資料下載權限是由商業帳戶管理員所自訂,則該權限取決於商業帳戶管理員的配置,不論專頁的基本管理員是否擁有潛在顧客資料下載權限。

傳輸率限制

限速限制為 200 乘以 24,再乘以過去 90 天內為 Facebook 專頁所建立的潛在顧客數量。如果您在 24 小時時限內呼叫的次數超過此值,則您的要求會傳回錯誤。

按日期範圍篩選

/ads/lead_gen/export_csv/ 端點傳送 GET 要求,其中日期格式為 POSIXUNIX 時戳:

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,或者其晚於目前時間,則將使用目前時間。

  • 如果任何條目欠缺 TSV 格式的廣告編號或廣告群組編號,則可能是因以下原因所引致:

    • 潛在顧客資料從自主接觸的用戶當中產生。在此情況下,TSV 中的 is_organic 顯示為 1;在其他情況下,此值為 0
    • 潛在顧客資料可能是由廣告預覽所提交。
    • 要求潛在顧客資料的用戶沒有廣告帳戶的廣告客戶權限。

Webhooks

獲取名單型廣告的即時更新。

第 1 步:新手入門

瀏覽我們的 Webhook 新手入門指南,以設定端點並配置 Webhook。

第 2 步:獲取長期專頁存取憑證

產生單個長期專頁憑證,以持續擷取資料而無需擔心憑證到期。

第 3 步:在專頁上安裝您的應用程式

瀏覽我們的專頁 Webhook 指南,了解如何在專頁上安裝您的應用程式。

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}/
'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);
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);
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, )
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(); } }
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 ,'')

成功的話,您的應用程式就會收到以下回應:

{
  "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 儲存庫查看此操作的範例。

批量讀取

應用程式如在 2018 年 7 月 2 日之後建立,則必須使用 leads_retrieval 權限來讀取潛在顧客資料。

leads 同時存在於廣告群組和表格節點中。此動作將會傳回所有與相應物件有關的資料。由於表格可以在多個廣告中重複使用,因此您表格包含的潛在顧客可以遠超過使用表格的廣告。

如要按廣告批量讀取,請使用以下程式碼:

curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v21.0/{adgroup-id}/leads
'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);
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);
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, )
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(); } }
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: { }, })

如要按表格讀取,請使用以下程式碼:

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"
    }
  }
}

讀取商店定位工具問題值

商店定位工具問題與其他問題十分相似。商店定位工具問題亦將會設有欄位編號,以便在建立表格期間對應資料。系統也會像處理其他問題一樣傳送商店定位工具問題。所傳遞的值將來自所選位置的商店編號

例如,假設您有欄位編號為 selected_dealer 的商店定位工具問題。如要批量擷取潛在顧客資料,您可以呼叫:

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": 1729974666 } ]' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v21.0/{adgroup-id}/leads
'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);
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);
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, )
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(); } }
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}], })

status 包含是以下其中一種值。

運算子意思

LESS_THAN

篩選小於時戳的值。

GREATER_THAN

篩選大於時戳的值。

GREATER_THAN_OR_EQUAL

篩選大於或等於時戳的值。

憑證化

如果表格擁有自訂欄位編號,傳回的欄位及數值將為特定的欄位及數值。

資源