Реализация

Схема 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. Текущий продукт позволяет прикреплять форму с уровнем кампании (в отличие от присоединения на уровне группы объявлений или объявлений).

Последствия: Лиды можно разделять только на уровне form_id (т. е. на уровне кампании).

Для обработки клиентам необходимо использовать 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, проверка google_key аналогична настройке в Google Ads, чтобы быть более уверенным в том, что лид действителен. Сохраняйте этот ключ в тайне и обновляйте его в Google Ads, если есть основания полагать, что он широко просочился.

is_test Это поле имеет «необязательную» семантику. Если значение равно true, рассматривать этот лид как тестовый лид. Если значение равно false или поле отсутствует, рассматривать этот лид как допустимый производственный лид.
user_column_data Повторяющийся кортеж «ключ-значение», передающий отправленные пользователем данные.
  • user_column_data.column_id : Тип данных, отправленный пользователем.
  • User_column_data.column_value : Для каждого типа данных будет тип значения, заполняемый в зависимости от типа данных. Все наши текущие типы данных имеют значение user_column_data.string_value .
  • user_column_data.column_name : Удобочитаемый текст типа данных, отправленный пользователем. Это поле не всегда может быть заполнено, используйте вместо него column_id .
данные_пользователя_столбца.идентификатор_столбца Содержание User_column_data.string_value user_column_data.column_name (устарело)
"ПОЛНОЕ ИМЯ" Полное имя пользователя. "Полное имя"
"ИМЯ" Имя пользователя. "Имя"
"ФАМИЛИЯ" Фамилия пользователя. "Фамилия"
"ЭЛЕКТРОННАЯ ПОЧТА" Электронная почта пользователя. «Электронная почта пользователя»
"НОМЕР ТЕЛЕФОНА" Телефон пользователя в формате E.164 , например, "+11234567890" . «Телефон пользователя»
"ПОЧТОВЫЙ ИНДЕКС" Почтовый индекс пользователя. "Почтовый индекс"
"НАЗВАНИЕ КОМПАНИИ" Название компании пользователя. "Название компании"
"ДОЛЖНОСТЬ" Должность пользователя. "Должность"
"РАБОЧАЯ_ЭЛЕКТРОННАЯ ПОЧТА" Рабочий адрес электронной почты пользователя. «Рабочая почта»
"РАБОЧИЙ_ТЕЛЕФОН" Рабочий телефон пользователя. "Рабочий телефон"
"АДРЕС УЛИЦЫ" Почтовый адрес пользователя. "Адрес улицы"
"ГОРОД" Город пользователя. "Город"
"ОБЛАСТЬ" Регион пользователя. "Область"
"СТРАНА" Страна пользователя. "Страна"
"МОДЕЛЬ_ТРАНСПОРТНОГО СРЕДСТВА" Какая модель вас интересует? Н/Д
"ТИП_ТРАНСПОРТНОГО СРЕДСТВА" Какой тип транспортного средства вас интересует? Н/Д
"ПРЕДПОЧТИТЕЛЬНЫЙ_ДИЛЕР" Выберите предпочитаемого вами дилера Н/Д
"Срок_покупки_ТС" Когда вы планируете приобрести автомобиль? Н/Д
"СОСТОЯНИЕ_ТРАНСПОРТНОГО_СРЕДСТВА" Какое состояние транспортного средства вас интересует? Н/Д
"ПРАВО_ВЛАДЕНИЯ_ТРАНСПОРТНЫМ_СРЕДСТВОМ" У вас есть транспортное средство? "Н/Д"
"ТИП_ОПЛАТЫ_ТРАНСПОРТНОГО_СРЕДСТВА" Какой вариант владения транспортным средством вас интересует? Н/Д
"КОМПАНИЯ_РАЗМЕР" Каков размер вашей компании? Н/Д
"ГОДОВЫЕ_ПРОДАЖИ" Каков ваш годовой объем продаж? Н/Д
"ЛЕТ_В_БИЗНЕСЕ" Сколько лет вы занимаетесь бизнесом? Н/Д
"JOB_DEPARTMENT" В каком отделе вы работаете? Н/Д
"РОЛЬ_РАБОТЫ" Какова ваша должностная роль? Н/Д
"ОБРАЗОВАТЕЛЬНАЯ_ПРОГРАММА" Какая программа вас интересует? Н/Д
"КУРС_ОБРАЗОВАНИЯ" Какой курс вас интересует? Н/Д
"ПРОДУКТ" Какой продукт вас интересует? Н/Д
"УСЛУГА" Какая услуга вас интересует? Н/Д
"ПРЕДЛОЖЕНИЕ" Какое предложение вас интересует? Н/Д
"КАТЕГОРИЯ" Какая категория вас интересует? Н/Д
"ПРЕДПОЧТИТЕЛЬНЫЙ_МЕТОД_КОНТАКТА" Выберите предпочитаемый способ связи Н/Д
"ПРЕДПОЧТИТЕЛЬНОЕ_МЕСТОПОЛОЖЕНИЕ" Выберите предпочитаемое вами местоположение Н/Д
"PREFERRED_CONTACT_TIME" В какое время лучше всего с вами связаться? Н/Д
"PURCHASE_TIMELINE" Когда вы планируете совершить покупку? Н/Д
"ЛЕТ_ОПЫТА" Сколько лет опыта работы у вас? Н/Д
"РАБОТА_ИНДУСТРИЯ" В какой отрасли вы работаете? Н/Д
"УРОВЕНЬ_ОБРАЗОВАНИЯ" Какой у вас наивысший уровень образования? Н/Д
"ТИП_СВОЙСТВА" Какой тип недвижимости вы ищете? Н/Д
"REALTOR_HELP_GOAL" В чем вам нужна помощь риелтора? Н/Д
"PROPERTY_COMMUNITY" Какое сообщество вас интересует? Н/Д
"ДИАПАЗОН_ЦЕН" Какой ценовой диапазон вас интересует? Н/Д
"NUMBER_OF_SPALONS" Сколько спален вы ищете? Н/Д
"МЕБЛИРОВАННАЯ_НЕДВИЖИМОСТЬ" Вы ищете полностью меблированную недвижимость? Н/Д
"PETS_ALLOWED_PROPERTY" Вы ищете недвижимость, где разрешено проживание с домашними животными? Н/Д
"СЛЕДУЮЩАЯ_ПЛАНИРУЕМАЯ_ПОКУПКА" Какой следующий продукт вы планируете приобрести? Н/Д
"EVENT_SIGNUP_INTEREST" Хотите зарегистрироваться на мероприятие? Н/Д
"ПРЕДПОЧТИТЕЛЬНЫЕ_МЕСТА_ДЛЯ_ПОКУПОК" Где вас интересует шопинг? Н/Д
"ЛЮБИМЫЙ_БРЕНД" Какой ваш любимый бренд? Н/Д
"ТРАНСПОРТНАЯ_КОММЕРЧЕСКАЯ_ЛИЦЕНЗИЯ_ТИП" Какой тип действующей коммерческой лицензии у вас есть? Н/Д
"СОБЫТИЕ_БРОНИРОВАНИЕ_ИНТЕРЕС" Хотите забронировать мероприятие? Н/Д
"СТРАНА_НАЗНАЧЕНИЯ" В какую страну вы направляетесь? Н/Д
"ГОРОД_НАЗНАЧЕНИЯ" Какой город назначения? Н/Д
"СТРАНА_ВЫЛЕТА" Из какой страны вы вылетаете? Н/Д
"ГОРОД_ВЫЛЕТА" Из какого города Вы вылетаете? Н/Д
"ДАТА_ОТПРАВЛЕНИЯ" Укажите дату вашего отъезда. Н/Д
"ДАТА_ВОЗВРАТА" Когда вы вернетесь? Н/Д
"NUMBER_OF_TRAVELERS" Со сколькими людьми вы путешествуете? Н/Д
"ПУТЕШЕСТВИЕ_БЮДЖЕТ" Каков ваш бюджет на поездку? Н/Д
"ПУТЕШЕСТВИЕ_РАЗМЕЩЕНИЕ" Где вы хотите остановиться во время путешествия? Н/Д
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 {"сообщение: Периодически повторяющаяся ошибка, необязательное сообщение"} Да

Дубликаты

Нет гарантии, что один лид будет доставлен ровно один раз, поэтому веб-хук обработки лидов должен корректно обрабатывать дубликаты.