行銷 API

擷取潛在顧客

有兩種方法可讀取潛在顧客：Webhooks 或整批讀取。

準備工作

若要讀取廣告特定的欄位（例如 ad_id、campaign_id），您需要：

若要讀取所有潛在顧客資料和廣告層級資料，您需要：

注意：如果該頁面管理員從未自訂潛在顧客，也沒有使用潛在顧客資料下載權限管理員授予存取權限，則所有頁面管理員都將具有潛在顧客資料下載權限。如果潛在顧客資料下載權限是由企業管理平台管理員自訂，則粉絲專頁基本管理員是否具有潛在顧客資料下載權限，皆取決於企業管理平台管理員的設定。

速率限制

速率限制是 200 乘以 24 乘以過去 90 天內為 Facebook 粉絲專頁建立的潛在顧客數量。如果您在 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，或其值大於目前時間，系統將使用目前時間。

  • 如果 TSV 中的任何項目缺少廣告編號或 Adgroup 編號，可能是因為下列原因：

    • 潛在顧客是由自主觸及人數產生。在此情況下，TSV 中的 is_organic 將顯示 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 存放庫中看到此實作的範例。

批量讀取

2018 年 7 月 2 日之後建立的應用程式會強制使用 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"
    }
  }
}

讀取商店定位工具問題的值

商店定位工具問題和其他任何的問題並無不同。商店定位工具問題將會具有欄位編號，用來在建立表單時對應欄位。商店定位工具問題的傳送方式也和其他的問題相同。系統傳遞的值會來自於所選地點的商店編號。

例如，如果有一個商店定位工具問題，其欄位編號是 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": 1731610803
       }
     ]' \
  -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

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

權杖化

如果表單有自訂的欄位編號，則傳回的欄位與數值將是特定的欄位與數值。

資源