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

Получить лиды можно тремя способами: путем скачивания файла TSV, массового чтения и с помощью Webhooks.

Разрешения

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

  • С помощью маркера доступа к Странице, т. е. маркера доступа, принадлежащего администратору Страницы. С помощью маркера доступа к Странице можно также считывать отдельные поля рекламы, такие как ad_id и campaign_id, если у вас есть по крайней мере разрешения рекламодателя для рекламного аккаунта, связанного с рекламой для лидов.
  • С помощью пользовательского маркера доступа, принадлежащего администратору Страницы. Для доступа ко всем данным лидов и данным уровня объявлений маркер доступа должен иметь области действия manage_pages и ads_management.

Чтобы получить информацию о лиде после получения ID лида с помощью Webhooks, необходимо также запросить разрешение leads_retrieval для API Lead Retrieval и разрешение manage_pages и пройти Проверку приложения.

Вскоре мы прекратим пересылать данные, собранные через формы рекламы для лидов, с помощью Webhooks в приложения в режиме разработчика. Изменения вступят в силу с 1 февраля 2019 года.

Управлять правами пользователей можно с помощью ролей на Странице.

Скачивание файла TSV

Конкретную форму генерации лидов можно запросить напрямую. Обратите внимание на то, что поле в ответе называется leadgen_export_csv_url, хотя поддерживается только формат 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>

Ответ:

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

Фильтрация

Полученный в ответе URL можно при необходимости отфильтровать, чтобы скачать лиды за определенный диапазон дат. Используйте параметры from_date и to_date для указания количества секунд, прошедших с начала «эры Unix», в формате времени POSIX или UNIX. Например, так можно скачать лиды за период с 13.01.2016 18:20:31 UTC по 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

Примечание.

  • Если параметр from_date не задан или его значение указывает на момент времени до создания формы, используется время создания формы.
  • Если параметр to_date не задан или его значение больше текущего времени, используется текущее время.

Если какие-либо элементы в файле TSV не имеют значений ID объявления или ID рекламной группы, причины могут быть следующими:

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

Массовое чтение

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

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

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

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

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 \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<LEAD_ID>?fields=custom_disclaimer_responses"

Ответ:

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

Фильтрация лидов

В этом примере лиды фильтруются в соответствии с меткой времени. Метки должны иметь формат времени 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

Токенизация

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

Webhooks

Вы можете получать новую информацию в режиме реального времени в процессе заполнения форм лидов. Посмотрите видео об использовании рекламы для лидов с Webhooks.

Данные из рекламы для лидов можно передавать во многие системы CRM в режиме реального времени. См. статью, посвященную интеграции с CRM.

Настройка

1. Настройте обработку запросов эндпойнтом в режиме реального времени

Ниже показана структура запроса для получения обновлений в режиме реального времени. Дополнительную информацию можно найти в записи блога об обновлениях в режиме реального времени.

В рамках одного запроса в массиве может передаваться несколько изменений.

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

Ответ:

{
  "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. Подпишите приложение на события генерации лидов

Для подписки на событие leadgen ваш сервер должен отправлять в ответ запросы HTTP GET, как описано в разделе, посвященном получению обновлений API в режиме реального времени с помощью Webhooks.

Настроив URL обратного вызова, подпишитесь на Webhook leadgen на панели приложений или с помощью вызова API:

Чтобы подписаться через API, вам потребуется маркер доступа приложения, а не пользователя:

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. Получите маркер доступа к Странице

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

  1. Получите обычный маркер доступа пользователя.
  2. Преобразуйте его в долгосрочный маркер.
  3. Используя долгосрочный маркер доступа пользователя, запросите маркер доступа к Странице:
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: { }, })

Ответ:

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

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

4. Подпишите страницу на приложение

Используя access_token страницы, которую нужно подписать, выполните приведенный ниже вызов, чтобы аутентифицировать приложение. Минимальное разрешение на доступ к странице, необходимое для выполнения этого действия: MODERATE_CONTENT.

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

Связанное с маркером приложение Facebook аутентифицируется для получения обновлений страницы. Указывать ID приложения не нужно.

В случае успешной подписки запросы при наступлении событий выполняются в режиме реального времени с задержкой не более нескольких минут. См. раздел, посвященный устранению неполадок при интеграции обновлений в режиме реального времени.