API Marketing

Truy xuất dữ liệu khách hàng tiềm năng

Bạn có thể đọc dữ liệu khách hàng tiềm năng bằng Webhooks hoặc tính năng Đọc dữ liệu hàng loạt.

Trước khi bạn bắt đầu

Để đọc các trường cụ thể của quảng cáo như ad_id, campaign_id, bạn cần:

Để đọc tất cả dữ liệu khách hàng tiềm năng và dữ liệu ở cấp độ quảng cáo, bạn sẽ cần có:

Lưu ý: Nếu quản trị viên trang này chưa từng tùy chỉnh khách hàng tiềm năng – hay quyền truy cập cụ thể nào bằng Trình quản lý quyền truy cập dữ liệu khách hàng tiềm năng – thì TẤT CẢ quản trị viên trang đều sẽ có quyền truy cập dữ liệu khách hàng tiềm năng. Nếu quản trị viên doanh nghiệp tùy chỉnh quyền truy cập dữ liệu khách hàng tiềm năng thì việc quản trị viên cơ bản của trang có quyền truy cập dữ liệu khách hàng tiềm năng hay không sẽ phụ thuộc vào cách cấu hình của quản trị viên doanh nghiệp.

Giới hạn tốc độ

Giới hạn tốc độ bằng 200 x 24 x số khách hàng tiềm năng được tạo trong 90 ngày qua cho một Trang Facebook. Nếu bạn thực hiện nhiều lệnh gọi hơn so với giới hạn này trong vòng 24 giờ, yêu cầu của bạn sẽ trả về lỗi.

Lọc theo khoảng ngày

Gửi yêu cầu GET đến điểm cuối /ads/lead_gen/export_csv/, trong đó ngày ở định dạng nhãn thời gian POSIX hoặc 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"

Cảnh báo

  • Nếu bạn không đặt from_date hoặc ngày này sớm hơn thời gian tạo mẫu, thời gian tạo mẫu sẽ được sử dụng.

  • Nếu bạn không đặt to_date hoặc ngày này muộn hơn thời gian hiện tại, thời gian hiện tại sẽ được sử dụng.

  • Nếu bất kỳ mục nào trong file TSV thiếu ID quảng cáo hoặc ID nhóm quảng cáo thì có thể là do những nguyên nhân sau đây:

    • Khách hàng tiềm năng được tạo từ số người xem tự nhiên. Trong trường hợp này, is_organic trong TSV sẽ hiển thị 1. Nếu không, giá trị sẽ là 0.
    • Dữ liệu khách hàng tiềm năng có thể được gửi từ một Bản xem trước quảng cáo.
    • Người yêu cầu dữ liệu khách hàng tiềm năng không có đặc quyền của nhà quảng cáo trên Tài khoản quảng cáo.

Webhooks

Nhận thông tin mới theo thời gian thực cho quảng cáo tìm kiếm khách hàng tiềm năng.

Bước 1: Bắt đầu

Hãy xem hướng dẫn Bắt đầu sử dụng Webhooks của chúng tôi để thiết lập điểm cuối và đặt cấu hình webhook.

Bước 2: Lấy Mã truy cập Trang dài hạn

Hãy tạo một Mã truy cập Trang dài hạn để liên tục tìm nạp dữ liệu mà không phải lo mã hết hạn.

Bước 3: Cài đặt ứng dụng của bạn trên Trang

Hãy xem hướng dẫn về Webhooks cho Trang của chúng tôi để tìm hiểu cách cài đặt ứng dụng trên Trang.

Phản hồi webhook

Khi tạo quảng cáo tìm kiếm khách hàng tiềm năng, ứng dụng của bạn sẽ nhận được phản hồi webhook sau đây:

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
          )
        )
      )
    )
  )
)

Bạn có thể dùng leadgen_id để truy xuất dữ liệu liên kết với khách hàng tiềm năng:

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

Khi thành công, ứng dụng của bạn sẽ nhận được phản hồi sau đây:

{
  "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"
    ]
  }],
  ...
}

Tìm hiểu thêm

Bạn có thể xem ví dụ về cách triển khai này trong kho lưu trữ Github của chúng tôi.

Đọc dữ liệu hàng loạt

Những ứng dụng được tạo sau ngày 02/07/2018 buộc phải sử dụng quyền leads_retrieval để đọc dữ liệu khách hàng tiềm năng.

Mã leads có trên cả nút nhóm quảng cáo và nút mẫu. Mã này trả về mọi dữ liệu liên kết với những đối tượng tương ứng. Do một mẫu có thể được dùng lại cho nhiều quảng cáo nên mẫu của bạn có thể chứa nhiều dữ liệu khách hàng tiềm năng hơn lượng dữ liệu mà một quảng cáo sử dụng.

Cách đọc dữ liệu hàng loạt theo quảng cáo:

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

Cách đọc dữ liệu theo mẫu:

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

Phản hồi:

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

Đọc giá trị của câu hỏi công cụ tìm vị trí cửa hàng

Câu hỏi công cụ tìm vị trí cửa hàng không khác với các câu hỏi khác. Câu hỏi công cụ tìm vị trí cửa hàng cũng có ID trường sẽ được đối ghép với vị trí cửa hàng trong khi tạo mẫu. Các câu hỏi này cũng sẽ được gửi tương tự như những câu hỏi khác. Giá trị được chuyển sẽ lấy từ Số cửa hàng của vị trí đã chọn.

Ví dụ: giả sử bạn có câu hỏi công cụ tìm vị trí cửa hàng với selected_dealer là ID trường. Để tìm nạp hàng loạt dữ liệu khách hàng tiềm năng, bạn có thể gọi:

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

Phản hồi:

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

Đọc các phản hồi về tuyên bố miễn trừ trách nhiệm tùy chỉnh

field_data không có phản hồi cho các ô đánh dấu (không bắt buộc) tuyên bố miễn trừ trách nhiệm tùy chỉnh mà người dùng sẽ điền vào. Để truy xuất các phản hồi này, hãy dùng trường custom_disclaimer_responses.

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

Phản hồi:

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

Lọc dữ liệu khách hàng tiềm năng

Ví dụ này lọc dữ liệu khách hàng tiềm năng dựa trên nhãn thời gian. Nhãn thời gian phải theo định dạng Unix.

curl -X GET \
  -d 'filtering=[
       {
         "field": "time_created",
         "operator": "GREATER_THAN",
         "value": 1731609104
       }
     ]' \
  -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 có một trong các giá trị sau.

Toán tửÝ nghĩa

LESS_THAN

Lọc các giá trị sớm hơn nhãn thời gian.

GREATER_THAN

Lọc các giá trị muộn hơn nhãn thời gian.

GREATER_THAN_OR_EQUAL

Lọc các giá trị muộn hơn hoặc bằng nhãn thời gian.

Mã hóa

Nếu mẫu có ID trường tùy chỉnh, các trường và giá trị trả về sẽ là các trường và giá trị được chỉ định.

Thông tin và nguồn lực