擷取潛在顧客名單

您有三個方法查閱潛在顧客名單:下載 TSV、批量查閱,以及使用 Webhooks。

權限

您可使用以下方法讀取潛在顧客名單或即時更新:

  • 使用專頁存取憑證,即專頁管理員的專頁存取憑證。專頁存取憑證還可讓您讀取廣告的特定欄位,例如 ad_idcampaign_id 等,前提是您至少擁有與潛在顧客名單廣告相關的廣告帳戶之廣告客戶級別權限。
  • 使用屬於專頁管理員的用戶存取憑證。存取憑證必須擁有 manage_pagesads_management 範圍,方可存取所有潛在顧客名單數據及廣告級別數據。

如要在經 Webhooks 收到潛在顧客名單編號後擷取潛在顧客名單資訊,您還需要要求獲取潛在顧客名單擷取 API leads_retrieval 的權限,以及 manage_pages 權限,並將應用程式提交至應用程式審查

我們將會停止把透過 Webhooks 在潛在顧客名單廣告表格中收集的數據傳送至開發模式的應用程式。此變更將於 2019 年 2 月 1 日起生效。

您可使用專頁角色管理用戶權限。

下載 TSV

您可以直接查詢特定的開發潛在顧客表格。請注意,欄位的標籤雖然為 leadgen_export_csv_url,但系統只能支援 TSV 格式。

use FacebookAds\Object\LeadgenForm;

$form = new LeadgenForm(<FORM_ID>);
$form->read();
from facebookads.adobjects.leadgenform import LeadgenForm

form = LeadgenForm(<LEADGEN_FORM_ID>)
form.remote_read()
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<FORM_ID>

回應:

{
  "id": "<LEAD_GEN_FORM_ID>",
  "leadgen_export_csv_url": "https://www.facebook.com/ads/lead_gen/export_csv?type=form&amp;id=<FORM_ID>",
  "locale": "en_US",
  "name": "My Form",
  "status": "ACTIVE"
}

篩選

您可選擇篩選網址回應,以下載特定日期範圍的潛在顧客名單。請使用 POSIXUNIX 時間格式的 from_dateto_date,以列明自時間起點以來經歷的秒數。例如,如要下載由 2016 年 1 月 13 日 18:20:31 (UTC) 至 2016 年 1 月 14 日 18:20:31 (UTC) 期間的潛在顧客名單:

https://www.facebook.com/ads/lead_gen/export_csv/?id=<FORM_ID>&amp;type=form&amp;from_date=1482698431&amp;to_date=1482784831

請注意:

  • 如果您沒有設定 from_date,或此值早於表格建立時間,則系統會使用表格建立時間。
  • 如果您沒有設定 to_date,或此時間戳記早於當前時間,則系統會使用當前時間。

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

  • 潛在顧客名單由自然散佈接觸人數所產生。若是這種情況,TSV 格式的 is_organic 將顯示為 1,否則該值將顯示為 0。
  • 潛在顧客名單可能是由廣告預覽所提交。
  • 有人在沒有廣告帳戶廣告客戶權限的情況下下載潛在顧客名單,並正在執行潛在顧客名單廣告。

批量查閱

leads 存在於廣告群組及表格節點中。此動作將會傳回所有與相應對象有關的數據。由於一份表格可用於多個廣告,您的表格包含的潛在顧客名單會遠超過使用表格的廣告。

如要按廣告批量查閱:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$leads = $ad->getLeads();
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
leads = ad.get_leads()
APINodeList<Lead> leads = new Ad(<AD_ID>, context).getLeads()
  .execute();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/leads

如要按表格查閱:

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 \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<LEAD_ID>?fields=custom_disclaimer_responses"

回應:

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

篩選潛在顧客名單

此範例將按時間戳記篩選潛在顧客名單。時間戳記必須為 Unix 時間戳記。

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdReportRunFields;

$ad = new Ad(<AD_ID>);
$time_from = (new \DateTime("-1 week"))->getTimestamp();
$leads = $ad->getLeads(array(), array(
  AdReportRunFields::FILTERING => array(
    array(
      'field' => 'time_created',
      'operator' => 'GREATER_THAN',
      'value' => $time_from,
    ),
  ),
));
curl -G \
  --data-urlencode 'filtering=[ 
    { 
      "field": "time_created", 
      "operator": "GREATER_THAN", 
      "value": 1516682744 
    } 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/leads

憑證化

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

Webhooks

在系統填寫潛在顧客名單時取得即時更新資訊。詳情請參閱使用 Webhooks 的潛在顧客名單廣告 - 影片

許多 CRM 都會提供即時更新資訊,以遷移潛在顧客名單廣告數據至 CRM。詳情請參閱可用的 CRM 整合功能

設定

1.設定端點以處理即時 Ping

即時更新資訊的 Ping 結構如下。詳情請參閱即時更新資訊 - 網誌

您可以透過更改陣列的 Ping 作出多次更改。

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/v3.1/{lead-id}/
const adsSdk = require('facebook-nodejs-ads-sdk'); const Lead = adsSdk.Lead; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.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 = { }; let 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 = '<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 )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.lead import Lead from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<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 = \"<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 = '<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"
    ]
  }],
  ...
}

2.為應用程式訂閱開發潛在顧客事件

如要訂閱 leadgen 事件,您的伺服器需要按照透過 Webhooks 接收即時 API 更新資訊中的指示,使用 HTTP GET 要求作出回應。

完成設定您的回調網址後,在應用程式的管理中心或透過 API 呼喚訂閱 leadgen webhook:

如要透過 API 作出訂閱,您需要提供應用程式存取憑證,而非用戶存取憑證:

curl \
-F "object=page" \
-F "callback_url=https://www.yourcallbackurl.com" \
-F "fields=leadgen" \
-F "verify_token=abc123" \
-F "access_token=<APP_ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<APP_ID>/subscriptions"

3.取得網頁憑證

請產生單一長期網頁憑證,以便持續地獲取數據,同時無需擔心憑證過期:

  1. 取得一般用戶憑證。
  2. 將之轉換至長期憑證
  3. 使用長期用戶憑證要求獲取網頁憑證:
curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/{user-id}/accounts
const adsSdk = require('facebook-nodejs-ads-sdk'); const User = adsSdk.User; const Page = adsSdk.Page; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.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 = { }; let accountss = (new User(id)).getAccounts( fields, params ); logApiCallResult('accountss api call complete.', accountss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\User; use FacebookAds\Object\Page; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new User($id))->getAccounts( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.user import User from facebookads.adobjects.page import Page from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print User(id).get_accounts( 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 = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new User(id, context).getAccounts() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end user = FacebookAds::User.get(id) accountss = user.accounts({ fields: { }, })

回應:

{
  "data": [
    {
      "access_token": "[REDACTED]",
      "category": "Pet",
      "name": "Puppy",
      "id": "153125381133",
      "perms": [
        "ADMINISTER",
        "EDIT_PROFILE",
        "CREATE_CONTENT",
        "MODERATE_CONTENT",
        "CREATE_ADS",
        "BASIC_ADMIN"
      ]
    },
  ]
}

此長期網頁憑證不會過期,而且您可於簡單 RTU 整合將之用硬式編碼寫入,以獲取潛在顧客名單數據。

4.為應用程式訂閱網頁

使用您需要訂閱的網頁之 access_token,執行下方的呼喚以為網頁驗證應用程式。您需要最少擁有此網頁的 MODERATE_CONTENT 權限,方可執行此動作。

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

Api::instance()->call(
  '/' . <PAGE_ID> . '/subscribed_apps',
  RequestInterface::METHOD_POST);
curl \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/subscribed_apps

針對頁面更新驗證與您的憑證建立聯繫的 Facebook 應用程式;您無需列明應用程式編號。

成功完成後,即時 Ping 將顯示於事件上,延遲最多幾分鐘。詳情詳參閱解決有關即時整合的疑難