POST-схема
POST-запрос, отправленный на веб-перехватчик, будет в формате JSON со следующей схемой:
Полезная нагрузка прототипа вебхука
// Represent user lead data for single column
message UserLeadColumnData {
// Human-readable text of the field type (e.g.: Full Name, What is your
// preferred dealership?). This field might not always be populated.
optional string column_name = 1;
// Column value based on column type
oneof column_value {
string string_value = 2;
}
// Column id. Populated for all types of fields. (e.g.: FULL_NAME)
optional string column_id = 3;
}
// Message to construct webhook JSON payload
message WebhookLead {
// Unique id to represent lead
optional string lead_id = 1;
// User inputted data per column
repeated UserLeadColumnData user_column_data = 2;
// API version
optional string api_version = 3;
// Form id to which lead belonged to.
optional int64 form_id = 4;
// Campaign id that the lead form is associated with
optional int64 campaign_id = 5;
// Key to be used by advertiser to verify the request
// is from Google.
optional string google_key = 6;
// Denotes if the lead is a test lead.
optional bool is_test = 7;
// Click ID for the lead submission.
optional string gcl_id = 8;
// Adgroup id which generated the lead.
optional int64 adgroup_id = 9;
// Creative id which generated the lead.
optional int64 creative_id = 10;
// Asset group id represents the container for holding assets, associated
// urls, hints and criteria that will be used to select assets and for
// optimization. This field is only populated for Performance Max campaigns.
int64 asset_group_id = 11;
}
Описание поля
Поле | Описание | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id | Уникальная строка, идентифицирующая данный лид. Рекомендации по обработке: используйте это для дедупликации полученных потенциальных клиентов. Это будет уникально во всех формах. При сообщении о проблемах, связанных с конкретным лидом, потребуется этот идентификатор. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version | Версия API, которой принадлежит эта схема лида. Это будет использоваться при переходе на новую схему, и пока его можно игнорировать. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id | Уникальный идентификатор для каждой формы, настроенной в Google Рекламе. Текущий продукт позволяет прикреплять форму на уровне кампании (а не на уровне группы объявлений или объявлений). Выводы: потенциальные клиенты могут быть разделены только на уровне Для обработки клиентам необходимо использовать целое число длиной 8 байт. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id | Идентификатор кампании Google Рекламы или идентификатор позиции (Display & Video 360) из прикрепленной формы для потенциальных клиентов. Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id | Идентификатор группы объявлений Google Рекламы используется для различения конкретной группы объявлений в кампании. (Доступно только для потенциальных клиентов из видеообъявлений и объявлений Discovery) Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id | Идентификатор объявления Google Рекламы используется для идентификации конкретного объявления в группе объявлений. (Доступно только для потенциальных клиентов из видеообъявлений и объявлений Discovery) Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id | Идентификатор клика Google — уникальный параметр, используемый для отслеживания каждого клика по объявлению. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key | Ключ, настроенный рекламодателем для каждой формы. Рекомендации по обработке: перед обработкой запроса, полученного через веб-перехватчик, проверка | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test | Это поле имеет «необязательную» семантику. Если значение истинно, рассматривайте это отведение как тестовое. Если значение ложно или поле отсутствует, рассматривайте этот интерес как действительный производственный интерес. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data | Повторяющийся кортеж «ключ-значение», передающий отправленные пользователем данные.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id | Это поле заполняется только для кампаний с максимальной эффективностью. Обозначает идентификатор контейнера, содержащего форму для потенциальных клиентов. Для обработки клиентам необходимо использовать 8-байтовое целое число. |
Обработка потенциальных клиентов
Обработчики потенциальных клиентов должны ответить следующими HTTP-кодами:
HTTP-ответ | Тело ответа (JSON) | Повторяемая ошибка? |
---|---|---|
200 | {} | Н/Д |
4XX | {"сообщение: текст ошибки в произвольной форме, описывающий, что не так с запросом"} | Нет |
5XX | {"сообщение: необязательное сообщение о периодической повторяемой ошибке"} | Да |
Дубликаты
Не гарантируется, что один лид будет доставлен ровно один раз, поэтому вебхук для обработки лидов должен корректно обрабатывать дубликаты.