Получение лидов

Получить лиды можно с помощью Webhooks или путем массового чтения.

Прежде чем начать

Для считывания рекламных полей, например ad_id или campaign_id, вам понадобятся:

Для считывания всех данных лидов и данных на уровне объявления вам понадобятся:

Примечание. Если администраторы Страницы ещё не настраивали лиды и не предоставляли разрешения в Leads Access Manager, это значит, что разрешение на доступ к лидам есть у ВСЕХ администраторов Страницы. Если разрешение на доступ к лидам настроили администраторы компании, его наличие у обычного администратора Страницы будет зависеть от этой настройки.

Ограничения числа обращений

Ограничение числа обращений вычисляется по следующей формуле: 200 × 24 × количество лидов, созданных для Страницы Facebook за последние 90 дней. Если количество вызовов за 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 не имеют значений ID объявления или ID группы объявлений, причины могут быть следующими:

    • Лид сгенерирован в результате органического охвата. Для поля is_organic в файле TSV в этом случае установлено значение 1. В противном случае значение равно 0.
    • Возможно, лид был получен в результате предварительного просмотра рекламы.
    • Пользователь, запросивший лиды, не имеет прав рекламодателя в рекламном аккаунте.

Webhooks

Получайте обновления по рекламе для лидов в режиме реального времени.

Шаг 1. Начало работы.

Создайте конечную точку и настройте Webhooks, как описано в этом руководстве.

Шаг 2. Получение долгосрочного маркера доступа к Странице.

Сгенерируйте один долгосрочный маркер доступа к Странице, чтобы непрерывно получать данные, не беспокоясь о сроке действия маркера.

Шаг 3. Установка приложения на Страницу.

Чтобы узнать, как установить приложение на Страницу, ознакомьтесь с этим руководством.

Ответ 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}/
'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);
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);
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, )
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(); } }
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 ,'')

В случае успеха приложение получит следующий ответ:

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

Пакетное чтение

Приложения, созданные после 2 июля 2018 года, должны использовать для считывания лидов разрешение leads_retrieval.

У узлов рекламных групп и узлов форм есть граница контекста leads. Она возвращает все данные, связанные с соответствующим объектом. Так как одна форма может использоваться для нескольких объявлений, она может содержать гораздо больше лидов, чем связанное с ней объявление.

Массовое чтение лидов для объявления:

curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v21.0/{adgroup-id}/leads
'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);
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);
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, )
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(); } }
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: { }, })

Чтение лидов для формы:

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

Считывание значения вопроса для локатора магазинов

Вопрос локатора магазинов не отличается от других вопросов. У него также есть ID поля, который связывается с ним при создании формы. Отправка таких вопросов происходит так же, как и для вопросов других типов. Передаваемое значение берется из параметра Номер магазина выбранного местоположения.

Предположим, у вас есть вопрос локатора магазинов с ID поля 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": 1731610272 } ]' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v21.0/{adgroup-id}/leads
'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);
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);
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, )
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(); } }
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}], })

Поле operator имеет одно из следующих значений:

ОператорЗначение

LESS_THAN

Отфильтровывает значения меньше, чем метка времени.

GREATER_THAN

Отфильтровывает значения больше, чем метка времени.

GREATER_THAN_OR_EQUAL

Отфильтровывает значения больше, чем метка времени, или равные ей.

Токенизация

Если форма содержит ID настроенных полей, будут возвращаться указанные поля и значения.

Дополнительная информация