Реализация

Схема POST

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

Для обработки данных клиентам необходимо использовать 8-байтовое целое число.

creative_id Идентификатор креатива Google Ads используется для различения конкретного креатива в группе объявлений. (Доступно только для лидов, полученных из видео- и ознакомительных объявлений)

Для обработки данных клиентам необходимо использовать 8-байтовое целое число.

gcl_id Идентификатор клика Google (Google Click ID ) — это уникальный параметр, используемый для отслеживания каждого клика по объявлению.
google_key Ключ, устанавливаемый рекламодателем для каждой формы.

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

Дубликаты

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