Получить лиды можно с помощью Webhooks или путем массового чтения.
Для считывания рекламных полей, например ad_id
или campaign_id
, вам понадобятся:
pages_manage_metadata
(если используются Webhooks). Для считывания всех данных лидов и данных на уровне объявления вам понадобятся:
Примечание. Если администраторы Страницы ещё не настраивали лиды и не предоставляли разрешения в 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, как описано в этом руководстве.
Сгенерируйте один долгосрочный маркер доступа к Странице, чтобы непрерывно получать данные, не беспокоясь о сроке действия маркера.
Чтобы узнать, как установить приложение на Страницу, ознакомьтесь с этим руководством.
При генерации лида приложение получит следующий ответ 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}/
В случае успеха приложение получит следующий ответ:
{ "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
Чтение лидов для формы:
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": 1729974357
}
]' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/{adgroup-id}/leads
Поле operator
имеет одно из следующих значений:
Оператор | Значение |
---|---|
| Отфильтровывает значения меньше, чем метка времени. |
| Отфильтровывает значения больше, чем метка времени. |
| Отфильтровывает значения больше, чем метка времени, или равные ей. |
Если форма содержит ID настроенных полей, будут возвращаться указанные поля и значения.