Реализация

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

Выводы: потенциальные клиенты могут быть разделены только на уровне form_id (т. е. на уровне кампании).

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

campaign_id Идентификатор кампании Google Рекламы или идентификатор позиции (Display & Video 360) из прикрепленной формы для потенциальных клиентов.

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

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

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

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

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

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

Рекомендации по обработке: перед обработкой запроса, полученного через веб-перехватчик, проверка google_key аналогична настройке в Google Рекламе, чтобы быть более уверенным в том, что запрос действителен. Сохраняйте этот ключ в тайне и обновляйте его в Google Рекламе, если есть основания полагать, что он стал широко известен.

is_test Это поле имеет «необязательную» семантику. Если значение истинно, рассматривайте это отведение как тестовое. Если значение ложно или поле отсутствует, рассматривайте этот интерес как действительный производственный интерес.
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" . «Телефон пользователя»
"ПОЧТОВЫЙ ИНДЕКС" Почтовый индекс пользователя. "Почтовый индекс"
"НАЗВАНИЕ КОМПАНИИ" Название компании пользователя. "Название компании"
"ДОЛЖНОСТЬ" Должность пользователя. "Должность"
"WORK_EMAIL" Рабочий адрес электронной почты пользователя. «Рабочая электронная почта»
"WORK_PHONE" Рабочий телефон пользователя. «Рабочий телефон»
"АДРЕС УЛИЦЫ" Адрес пользователя. "Адрес улицы"
"ГОРОД" Город пользователя. "Город"
"ОБЛАСТЬ" Регион пользователя. "Область"
"СТРАНА" Страна пользователя. "Страна"
"МАШИНА_МОДЕЛИ" Какая модель вас интересует? Н/Д
"ТРАНСПОРТНОЕ СРЕДСТВО_ТИП" Какой тип транспортного средства вас интересует? Н/Д
"PREFERRED_DEALERSHIP" Выберите предпочитаемый вами дилерский центр Н/Д
"VEHICLE_PURCHASE_TIMELINE" Когда вы планируете приобрести автомобиль? Н/Д
"АВТОМОБИЛЬ_СОСТОЯНИЕ" Какое состояние автомобиля Вас интересует? Н/Д
"VEHICLE_OWNERSHIP" У вас есть автомобиль? "Н/Д"
"VEHICLE_PAYMENT_TYPE" Какой вариант владения автомобилем вас интересует? Н/Д
"COMPANY_SIZE" Какого размера ваша компания? Н/Д
"ГОДОВЫЕ_ПРОДАЖИ" Каков ваш годовой объем продаж? Н/Д
"YEARS_IN_BUSINESS" Сколько лет вы занимаетесь бизнесом? Н/Д
"JOB_DEPARTMENT" Какой у вас отдел занятости? Н/Д
"JOB_ROLE" Какова ваша должность? Н/Д
"EDUCATION_PROGRAM" Какая программа вас интересует? Н/Д
"EDUCATION_COURSE" Какой курс вас интересует? Н/Д
"ПРОДУКТ" Какой продукт вас интересует? Н/Д
"УСЛУГА" Какая услуга вас интересует? Н/Д
"ПРЕДЛОЖЕНИЕ" Какое предложение вас интересует? Н/Д
"КАТЕГОРИЯ" Какая категория вас интересует? Н/Д
"PREFERRED_CONTACT_METHOD" Выберите предпочтительный способ связи Н/Д
"PREFERRED_LOCATION" Выберите предпочитаемое местоположение Н/Д
"PREFERRED_CONTACT_TIME" В какое время лучше всего с вами связаться? Н/Д
"PURCHASE_TIMELINE" Когда вы собираетесь совершить покупку? Н/Д
"ГОДА_ОПЫТА" Сколько лет опыта работы у вас есть? Н/Д
"JOB_INDUSTRY" В какой отрасли вы работаете? Н/Д
"УРОВЕНЬ_ОБРАЗОВАНИЯ" Какой у вас высший уровень образования? Н/Д
"PROPERTY_TYPE" Какой тип недвижимости вы ищете? Н/Д
"REALTOR_HELP_GOAL" В чем вам нужна помощь риэлтора? Н/Д
"PROPERTY_COMMUNITY" Какое сообщество вам интересно? Н/Д
"PRICE_RANGE" Какой ценовой диапазон вы ищете? Н/Д
"NUMBER_OF_BEDROOMS" Сколько спален вы ищете? Н/Д
"МЕБЕЛЬНАЯ_СОБСТВЕННОСТЬ" Вы ищете полностью меблированную недвижимость? Н/Д
"PETS_ALLOWED_PROPERTY" Вы ищете недвижимость, в которой допускается размещение с домашними животными? Н/Д
"NEXT_PLANNED_PURCHASE" Какой следующий продукт вы планируете приобрести? Н/Д
"EVENT_SIGNUP_INTEREST" Хотите записаться на мероприятие? Н/Д
"PREFERRED_SHOPPING_PLACES" Где вам интересно совершать покупки? Н/Д
"ЛЮБИМЫЙ_БРЕНД" Какой ваш любимый бренд? Н/Д
"ТРАНСПОРТНАЯ_КОММЕРЧЕСКАЯ_ЛИЦЕНЗИЯ_ТИП" Какой тип действующей коммерческой лицензии у вас есть? Н/Д
"EVENT_BOOKING_INTEREST" Вы заинтересованы в бронировании мероприятия? Н/Д
"DESTINATION_COUNTRY" Какая у вас страна назначения? Н/Д
"DESTINATION_CITY" Какой у вас город назначения? Н/Д
"DEPARTURE_COUNTRY" Какая у вас страна отправления? Н/Д
"DEPARTURE_CITY" Какой у вас город отправления? Н/Д
"DEPARTURE_DATE" Какая у вас дата отъезда? Н/Д
"RETURN_DATE" Какая дата вашего возвращения? Н/Д
"NUMBER_OF_TRAVELERS" Со сколькими людьми вы путешествуете? Н/Д
"TRAVEL_BUDGET" Каков ваш бюджет на поездку? Н/Д
"TRAVEL_ACCOMMODATION" Где вы хотите остановиться во время путешествия? Н/Д
asset_group_id Это поле заполняется только для кампаний с максимальной эффективностью. Обозначает идентификатор контейнера, содержащего форму для потенциальных клиентов.

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

Обработка потенциальных клиентов

Обработчики потенциальных клиентов должны ответить следующими HTTP-кодами:

HTTP-ответ Тело ответа (JSON) Повторяемая ошибка?
200 {} Н/Д
4XX {"сообщение: текст ошибки в произвольной форме, описывающий, что не так с запросом"} Нет
5XX {"сообщение: необязательное сообщение о периодической повторяемой ошибке"} Да

Дубликаты

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