Схема POST
Запрос POST, отправленный на webhook, будет в формате JSON со следующей схемой:
Полезная нагрузка Webhook Proto
// 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 stage at the time of delivery.
string lead_stage = 12 [(datapol.semantic_type) = ST_NOT_REQUIRED];
// Lead submit time in ISO-8601 format. Ex- 2024-09-26T12:30:00Z
string lead_submit_time = 13 [(datapol.semantic_type) = ST_NOT_REQUIRED];
}
Описание поля
Поле | Описание | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id | Уникальная строка, идентифицирующая данный лид. Рекомендация по обработке: используйте это для дедупликации лидов, которые получены. Это будет уникально для всех форм. При сообщении о проблемах, связанных с определенным лидом, этот идентификатор будет необходим. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version | Версия API, к которой относится эта схема лида. Она будет использоваться при переходе на новую схему и может быть проигнорирована на данный момент. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id | Уникальный идентификатор для каждой формы, настроенной в Google Ads. Текущий продукт позволяет прикреплять форму с уровнем кампании (в отличие от присоединения на уровне группы объявлений или объявлений). Последствия: Лиды можно разделять только на уровне Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id | Идентификатор кампании Google Ads или идентификатор позиции (Display & Video 360) прикрепленной формы лидов. Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id | Идентификатор группы объявлений Google Ads используется для различения определенной группы объявлений в кампании. (Доступно только для лидов из видеорекламы и объявлений Discovery) Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id | Идентификатор креатива Google Ads используется для различения конкретного креатива в группе объявлений. (Доступно только для лидов из видеорекламы и объявлений Discovery) Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id | Идентификатор клика Google — уникальный параметр, используемый для отслеживания каждого клика по объявлению. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key | Ключ, настраиваемый рекламодателем для каждой формы. Рекомендация по обработке: Перед обработкой лида, полученного через webhook, проверка | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test | Это поле имеет «необязательную» семантику. Если значение равно true, рассматривать этот лид как тестовый лид. Если значение равно false или поле отсутствует, рассматривать этот лид как допустимый производственный лид. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data | Повторяющийся кортеж «ключ-значение», передающий отправленные пользователем данные.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id | Это поле заполняется только для кампаний Performance-Max. Это обозначает идентификатор контейнера, который содержит лид-форму. Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage | Это обозначает стадию лида на момент доставки лида. Это поле полезно для отслеживания стадии воронки/статуса конверсии лида. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time | Это обозначает временную метку, в которую пользователь отправил форму. Она представлена в формате ISO-8601. Например, 2024-09-26T12:30:00Z |
Нераспознанные поля и прямая совместимость
Чтобы обеспечить надежную интеграцию веб-перехватчика и возможность адаптации к будущим улучшениям, рекомендуется спроектировать анализатор JSON так, чтобы он корректно игнорировал любые поля в полезной нагрузке веб-перехватчика, которые ваша система явно не использует или не распознает.
Основная рекомендация: настройте логику анализа JSON для обработки только тех полей, которые вам требуются для вашего приложения. Не пишите код, который ожидает фиксированный набор полей или который даст сбой, если в полезной нагрузке будут присутствовать новые, неожиданные поля.
Почему это важно:
- Совместимость вперед: Google может добавлять новые, необязательные поля в полезную нагрузку веб-перехватчика в будущих обновлениях, чтобы предоставлять более полные данные или новые функции. Если ваш парсер слишком строг (например, не справляется с неизвестными свойствами), ваша интеграция может сломаться, когда такие неломающие изменения будут развернуты Google.
- Упрощенное обслуживание: сосредоточившись только на тех точках данных, которые вы активно используете, ваш код интеграции становится проще и легче в обслуживании.
Большинство современных библиотек анализа JSON по умолчанию предлагают возможность игнорировать неизвестные свойства или могут быть настроены для этого.
Обработка свинца
Обработчики лидов должны отвечать следующими HTTP-кодами:
HTTP-ответ | Тело ответа (JSON) | Повторяемая ошибка? |
---|---|---|
200 | {} | Н/Д |
4XX | {"сообщение: Текст ошибки в свободной форме, описывающий, что было не так с запросом"} | Нет |
5XX | {"сообщение: Периодически повторяющаяся ошибка, необязательное сообщение"} | Да |
Дубликаты
Нет гарантии, что один лид будет доставлен ровно один раз, поэтому веб-хук обработки лидов должен корректно обрабатывать дубликаты.