Mengambil Prospek

Ada tiga cara untuk membaca prospek: Unduhan TSC, membaca massal, dan dengan Webhooks.

Izin

Anda dapat membaca prospek atau pembaruan real-time dengan:

  • Menggunakana Token Akses Halaman, yaitu token akses pengurus Halaman untuk halaman. Token akses halaman juga memungkinkan Anda membaca kolom khusus iklan seperti ad_id, campaign_id, asalkan Anda memiliki minimal izin tingkat pengiklan pada akun iklan yang terkait dengan iklan prospek.
  • Menggunakan Token Akses Pengguna milik pengurus Halaman. Untuk mengakses semua data prospek dan data tingkat iklan, token akses harus memiliki lingkup manage_pages dan ads_management.

Untuk mengambil informasi prospek setelah ID prospek diterima melalui Webhooks, Anda juga harus meminta izin API Pengambilan Prospek leads_retrieval serta izin manage_pages dan mengirimkan aplikasi ke Tinjauan Aplikasi.

Kami akan berhenti mengirimkan data yang terkumpul di formulir Iklan Prospek melalui Webhooks ke aplikasi dalam Mode Pengembang. Kami mulai menerapkan perubahan ini pada 1 Februari 2019.

Anda dapat mengelola hak pengguna dengan peran Halaman.

Unduhan TSV

Anda dapat secara langsung melakukan kueri formulir penciptaan prospek. Perlu diperhatikan kolom diberi label leadgen_export_csv_url meski satu-satunya format yang didukung adalah 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>

Tanggapan:

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

Pemfilteran

Selain itu, Anda dapat memfilter tanggapan URL guna mengunduh prospek untuk rentang tanggal tertentu. Gunakan from_date dan to_date dalam format waktu POSIX atau UNIX, yang menyatakan angka detik. Misalnya, untuk mengunduh prospek dalam periode waktu mulai 13-01-2016 pukul 18:20:31 UTC dan berakhir pada 14-01-2016 pukul 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

Catatan:

  • Jika from_date tidak diatur, atau nilainya kurang dari tanggal pembuatan formulir, maka waktu saat pembuatan formulir yang digunakan.
  • Jika to_date tidak diatur, atau nilainya kurang dari tanggal pembuatan formulir, maka waktu saat pembuatan formulir yang digunakan.

Jika entri kekurangan ID Iklan atau ID Grup di dalam TSV, hal ini mungkin karena alasan berikut:

  • Prospek tersebut dihasilkan dari jangkauan organik. Dalam kasus ini, is_organic di TSV menampilkan 1. Jika tidak, nilainya adalah 0
  • Prospek tersebut mungkin dikirim dari Contoh Iklan.
  • Setiap orang yang mengunduh prospek tidak akan memiliki hak istimewa Pengiklan pada Akun Iklan yang menayangkan iklan Prospek.

Pembacaan Massal

leads berada pada grup iklan dan node formulir. Prospek ini mengembalikan semua data yang terkait dengan objeknya masing-masing. Oleh karena sebuah formulir dapat digunakan lagi untuk beberapa iklan, formulir Anda dapat berisi prospek yang jauh lebih banyak daripada iklan yang menggunakannya.

Untuk membaca secara massal berdasarkan iklan:

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

Untuk membaca menurut formulir:

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

Tanggapannya:

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

Membaca Nilai Pertanyaan Pencari Lokasi Toko

Pertanyaan pencari lokasi toko tidak berbeda dengan pertanyaan lain. Pertanyaan pencari lokasi toko juga memiliki ID kolom yang akan dipetakan selama pembuatan formulir. Pertanyaan tersebut juga akan dikirim seperti pertanyaan lain. Nilai yang diteruskan berasal dari Jumlah Toko dari lokasi yang dipilih.

Misalnya, katakanlah Anda memiliki pertanyaan pencari lokasi toko dengan selected_dealer sebagai ID kolom. Untuk mengambil data prospek secara massal Anda dapat memanggil:

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

Tanggapannya:

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

Membaca Tanggapan Penafian Khusus

field_data tidak berisi tanggapan untuk kotak centang penafian khusus opsional yang harus diisi oleh pengguna. Untuk mendapatkan tanggapan, Anda dapat menggunakan kolom custom_disclaimer_responses.

curl \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<LEAD_ID>?fields=custom_disclaimer_responses"

Tanggapan:

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

Memfilter Prospek

Contoh ini memfilter prospek berdasarkan cap waktu. Cap waktu harus berupa cap waktu 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

Tokenisasi

Jika formulir tersebut memiliki ID kolom, maka kolom dan nilai yang dikembalikan akan berupa kolom dan nilai tertentu.

Webhooks

Dapatkan pembaruan secara realtime jika prospek terisi. Lihat Iklan Prospek dengan Webhooks, Video.

Banyak CRM menyediakan pembaruan secara realtime untuk melakukan migrasi data iklan Prospek ke dalam CRM. Lihat Integrasi CRM yang Tersedia.

Penyiapan

1. Siapkan endpoint untuk menangani ping secara real time

Ping untuk pembaruan secara realtime terstruktur sebagai berikut. Baca selengkapnya di Pembaruan Real Time, Blog.

Beberapa perubahan dapat terjadi melalui ping pada deret perubahan.

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

Anda dapat menggunakan leadgen_id untuk mendapatkan data yang terkait dengan prospek tersebut:

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

Tanggapannya:

{
  "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. Berlangganan aplikasi untuk peristiwa penciptaan prospek

Untuk berlangganan peristiwa leadgen, server Anda harus menanggapi dengan permintaan HTTP GET seperti dijelaskan di Menerima Pembaruan API secara Real Time dengan Webhooks.

Setelah URL callback Anda disiapkan, berlanggananlah ke webhook leadgen di Dasbor Aplikasi atau melalui panggilan API:

Untuk berlangganan melalui API Anda membutuhkan token akses aplikasi, bukan token akses pengguna:

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. Mendapatkan token halaman

Buat token halaman tunggal dengan masa berlaku lama untuk terus mengambil data tanpa khawatir tentang waktu kedaluwarsanya:

  1. Mendapatkan token pengguna reguler.
  2. Ubah token menjadi token dengan masa berlaku lama
  3. dengan menggunakan token akses pengguna dengan masa berlaku lama, minta token halaman:
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: { }, })

Tanggapannya:

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

Token halaman yang sudah lama ada ini tidak memiliki tanggal berakhir dan Anda dapat melakukan hard-code pada token ini dalam integrasi RTU yang sederhana untuk mendapatkan data prospek.

4. Mendaftarkan langganan halaman ke aplikasi

Dengan menggunakan access_token untuk halaman yang perlu Anda perlukan untuk berlangganan, lakukan panggilan di bawah untuk mengauntetikasi aplikasi untuk halaman Anda. Anda harus memiliki minimal izin MODERATE_CONTENT ke halaman dalam rangka melakukan tindakan ini.

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

Aplikasi Facebook yang terkait dengan token Anda diautentikasi untuk pembaruan halaman; Anda tidak perlu menentukan ID aplikasi.

Jika berhasil, terjadi ping secara realtime pada peristiwa dengan penundaan hingga beberapa menit. Lihat Menyelesaikan Masalah Integrasi Real Time.