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

Có 3 cách để đọc dữ liệu khách hàng tiềm năng, đó là: Tải tệp TSV xuống, đọc dữ liệu hàng loạt và sử dụng Webhooks.

Các quyền

Bạn có thể đọc dữ liệu khách hàng tiềm năng hoặc thông tin cập nhật trong thời gian thực bằng cách:

  • Sử dụng Mã truy cập Trang, tức là mã truy cập của quản trị viên Trang cho trang đó. Nếu có tối thiểu các quyền ở cấp độ nhà quảng cáo trên tài khoản quảng cáo liên kết với quảng cáo tìm kiếm khách hàng tiềm năng, thì bạn cũng có thể sử dụng mã truy cập trang để đọc các trường cụ thể của quảng cáo như ad_id, campaign_id.
  • Sử dụng Mã truy cập người dùng thuộc về quản trị viên Trang. Để truy cập tất cả dữ liệu khách hàng tiềm năng và dữ liệu ở cấp độ quảng cáo, mã truy cập phải có phạm vi manage_pagesads_management.

Để truy xuất thông tin khách hàng tiềm năng khi nhận ID khách hàng tiềm năng qua Webhooks, bạn cũng cần yêu cầu quyền Truy xuất khách hàng tiềm năng qua API leads_retrieval cũng như quyền manage_pages và gửi ứng dụng của bạn đến quy trình Xét duyệt ứng dụng.

Chúng tôi sẽ ngừng gửi dữ liệu thu thập được trong các mẫu Quảng cáo tìm kiếm khách hàng tiềm năng qua Webhooks đến các ứng dụng ở Chế độ phát triển. Chúng tôi sẽ bắt đầu thực hiện thay đổi này từ ngày 1/2/2019.

Bạn có thể quản lý quyền của người dùng bằng các vai trò trên Trang.

Tải tệp TSV xuống

Bạn có thể truy vấn trực tiếp một mẫu tìm kiếm khách hàng tiềm năng cụ thể. Lưu ý rằng mặc dù chỉ hỗ trợ định dạng TSV nhưng trường này lại có nhãn leadgen_export_csv_url.

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>

Phản hồi:

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

Lọc

Bạn có thể tùy ý lọc phản hồi URL để tải xuống dữ liệu khách hàng tiềm năng cho khoảng ngày đã chỉ định. Hãy sử dụng from_dateto_date ở định dạng thời gian POSIX hoặc UNIX, biểu thị số giây kể từ ngày bắt đầu. Ví dụ: cách tải xuống dữ liệu khách hàng tiềm năng cho khoảng thời gian bắt đầu từ 13/01/2016 18:20:31 UTC và kết thúc vào 14/01/2016 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

Lưu ý:

  • Nếu không đặt from_date hoặc giá trị này sớm hơn thời gian tạo mẫu, thì thời gian tạo mẫu sẽ được sử dụng.
  • Nếu không đặt to_date hoặc dấu thời gian muộn hơn thời gian hiện tại, thì thời gian hiện tại sẽ được sử dụng.

Nếu bất kỳ mục nhập nào trong tệp TSV thiếu ID quảng cáo hoặc ID nhóm quảng cáo, thì có thể là vì các lý do sau:

  • Khách hàng tiềm năng được tìm kiếm từ số người xem tự nhiên. Trong trường hợp này, is_organic trong tệp TSV hiển thị 1. Nếu không thì giá trị này sẽ bằng 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.
  • Bất kỳ ai tải dữ liệu khách hàng tiềm năng xuống đều thiếu các đặc quyền của Nhà quảng cáo đối với Tài khoản quảng cáo đang chạy Quảng cáo tìm kiếm khách hàng tiềm năng.

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

leads có trên cả nút nhóm quảng cáo và nút mẫu. Mã này trả về tất cả các dữ liệu được liên kết với những đối tượng tương ứng của chúng. Do mẫu có thể được sử dụng lại cho nhiều quảng cáo nên mẫu 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 dữ liệu hàng loạt theo quảng cáo:

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

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 tìm vị trí cửa hàng

Câu hỏi 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 tìm vị trí cửa hàng cũng có ID trường sẽ được ánh xạ tới vị trí cửa hàng trong khi tạo mẫu. Chúng cũng sẽ được gửi tương tự như các câu hỏi khác. Giá trị chuyển đi được lấy từ Số hiệu cửa hàng của vị trí đã chọn.

Giả sử bạn có câu hỏi tìm vị trí cửa hàng với selected_dealer là ID trường. Để tìm nạp hàng loạt khách hàng tiềm năng, bạn có thể thực hiện lệnh 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ố từ chối trách nhiệm tùy chỉnh

Trường field_data không chứa các phản hồi cho hộp kiểm tuyên bố từ chối trách nhiệm tùy chỉnh mà người dùng đã điền vào. Để truy xuất các phản hồi này, bạn có thể sử dụng trường custom_disclaimer_responses.

curl \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<LEAD_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 dấu thời gian. Các dấu thời gian phải là dấu thời gian ở định dạng 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

Mã hóa

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

Webhooks

Tải các bản cập nhật trong thời gian thực khi điền mẫu tìm kiếm khách hàng tiềm năng. Hãy xem Video về quảng cáo tìm kiếm khách hàng tiềm năng bằng Webhooks.

Nhiều công cụ Quản lý quan hệ khách hàng (CRM) cung cấp các bản cập nhật trong thời gian thực để di chuyển dữ liệu của Quảng cáo tìm kiếm khách hàng tiềm năng vào CRM. Hãy xem Tích hợp CRM hiện có.

Thiết lập

1. Thiết lập điểm cuối để xử lý các lần ping trong thời gian thực

Lệnh ping để nhận được các bản cập nhật trong thời gian thực có cấu trúc như sau. Hãy đọc thêm thông tin trong Bài viết trên blog có tên Các bản cập nhật trong thời gian thực.

Nhiều thay đổi có thể đi kèm lệnh ping trong mảng thay đổi đó.

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ể sử 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/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 ,'')

Phản hồi:

{
  "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. Đăng ký ứng dụng cho các sự kiện tìm kiếm khách hàng tiềm năng

Để đăng ký sự kiện leadgen, máy chủ của bạn phải phản hồi với các yêu cầu HTTP GET như được mô tả trong bài viết về Truy xuất các bản cập nhật API trong thời gian thực bằng Webhooks.

Sau khi thiết lập URL gọi lại, hãy đăng ký webhook leadgen trong Bảng điều khiển của ứng dụng hoặc thông qua lệnh gọi API:

Để đăng ký thông qua API, bạn cần có mã truy cập ứng dụng chứ không phải mã truy cập của người dùng:

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. Tạo mã truy cập trang

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:

  1. Tạo một mã truy cập thông thường của người dùng.
  2. Chuyển đổi mã này thành mã truy cập dài hạn
  3. với mã truy cập dài hạn của người dùng, hãy yêu cầu mã truy cập trang như sau:
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: { }, })

Phản hồi:

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

Mã truy cập trang dài hạn này không có ngày hết hạn và bạn có thể mã hóa cứng mã này trong các tích hợp RTU đơn giản để lấy dữ liệu khách hàng tiềm năng.

4. Đăng ký trang cho ứng dụng

Với access_token cho trang bạn cần đăng ký, hãy thực hiện lệnh gọi bên dưới để xác thực ứng dụng cho trang của bạn. Tối thiểu bạn cần có quyền MODERATE_CONTENT đối với trang để thực hiện hành động này.

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

Ứng dụng Facebook liên kết với mã truy cập của bạn được xác thực cho các bản cập nhật trang; bạn không cần phải chỉ định ID ứng dụng.

Khi thành công, các lệnh ping trong thời gian thực diễn ra trên các sự kiện có độ trễ lên tới vài phút. Hãy xem cách Khắc phục sự cố xảy ra với các tích hợp trong thời gian thực.