实现

POST 架构

发送到 webhook 的 POST 请求将采用 JSON 格式,其中包含以下 schema:

网络钩子 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;
}

字段说明

字段 说明
lead_id 用于标识指定潜在客户的唯一字符串。

处理建议:使用此选项可对 。该名称在所有表单中都是唯一的。报告时 与特定潜在客户相关的问题时,必须提供此 ID。

api_version 此潜在客户架构所属的 API 版本。在下列情况中, 迁移到新架构,可以暂时忽略。
form_id Google Ads 中配置的每个表单的唯一 ID。当前产品支持 在广告系列一级附加表单(而不是在广告组一级或广告一级附加表单) 级别)。

影响:只能在 form_id 对潜在客户进行细分 级别(即广告系列一级)。

客户端需要使用 8 个字节的整数进行处理。

campaign_id 相应广告客户的 Google Ads 广告系列 ID 或订单项 ID (Display &Video 360) 随附的潜在客户表单。

客户端需要使用一个 8 字节的整数进行处理。

adgroup_id Google Ads 广告组 ID 用于区分 广告组中的广告组。(适用于通过视频和发现广告发掘的潜在客户 广告)

客户端需要使用一个 8 字节的整数进行处理。

creative_id Google Ads 广告素材 ID 用于区分 广告素材。(适用于通过视频和发现广告发掘的潜在客户 广告)

客户端需要使用一个 8 字节的整数进行处理。

gcl_id Google 点击 ID 是用于跟踪广告每次点击的唯一参数。
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.column_id User_column_data.string_value 内容 user_column_data.column_name (已弃用)
“FULL_NAME” 用户的全名。 “全名”
“FIRST_NAME” 用户的名字。 “名字”
LAST_NAME 用户的姓氏。 “Last Name”
“EMAIL” 用户的电子邮件地址。 "User Email"
“PHONE_NUMBER” E.164 中的用户电话 格式,例如"+11234567890" "User Phone"
"POSTAL_CODE" 用户的邮政编码。 "Postal Code"
“COMPANY_NAME” 用户的公司名称。 “公司名称”
"JOB_TITLE" 用户的职位。 “职位”
“WORK_EMAIL” 用户的工作电子邮件地址。 “工作电子邮件地址”
WORK_PHONE 用户的工作电话。 “工作电话”
“STREET_ADDRESS” 用户的街道地址。 “街道地址”
“CITY” 用户所在的城市。 “城市”
“REGION” 用户所在的地区。 “区域”
“COUNTRY” 用户所在的国家/地区。 “国家/地区”
VEHICLE_MODEL 您对哪种车型感兴趣? 不适用
“VEHICLE_TYPE” 您对哪种类型的汽车感兴趣? 不适用
PREFERRED_DEALERSHIP 请选择您的首选经销商 不适用
“VEHICLE_PURCHASE_TIMELINE” 您计划何时购买汽车? 不适用
“VEHICLE_CONDITION” 您对哪种车况感兴趣? 不适用
“VEHICLE_OWNERSHIP” 您有汽车吗? “不适用”
"VEHICLE_PAYMENT_TYPE" 您有兴趣通过哪种方式到手一部车? 不适用
“COMPANY_SIZE” 贵公司的规模有多大? 不适用
“ANNUAL_SALES” 您每年的销量是多少? 不适用
YEARS_IN_BUSINESS 您的企业经营多少年了? 不适用
“JOB_DEPARTMENT” 您在哪个部门工作? 不适用
"JOB_ROLE" 您的职位是什么? 不适用
EDUCATION_PROGRAM 您对哪个课程/培训计划感兴趣? 不适用
“EDUCATION_COURSE” 您对哪种课程感兴趣? 不适用
“PRODUCT” 您对哪种产品感兴趣? 不适用
“SERVICE” 您对哪种服务感兴趣? 不适用
“OFFER” 您对哪种优惠感兴趣? 不适用
“CATEGORY” 您对哪种类别感兴趣? 不适用
"PREFERRED_CONTACT_METHOD" 请选择您的首选联系方式 不适用
PREFERRED_LOCATION 请选择您的首选位置 不适用
PREFERRED_CONTACT_TIME 什么时间与您联系最合适? 不适用
“PURCHASE_TIMELINE” 您想何时购买? 不适用
“YEARS_OF_EXPERIENCE” 您有几年工作经验? 不适用
"JOB_INDUSTRY" 您从事哪个行业? 不适用
“LEVEL_OF_EDUCATION” 您的最高学历是什么? 不适用
“PROPERTY_TYPE” 您想要哪种类型的房子? 不适用
“REALTOR_HELP_GOAL” 您需要房地产经纪人为您提供哪方面的帮助? 不适用
“PROPERTY_COMMUNITY” 您对哪个社区感兴趣? 不适用
“PRICE_RANGE” 您想要什么价位的? 不适用
“NUMBER_OF_BEDROOMS” 您想要多少个卧室? 不适用
“FURNISHED_PROPERTY” 您想要找家具齐全的房子吗? 不适用
“PETS_ALLOWED_PROPERTY” 您要找允许养宠物的房子吗? 不适用
“NEXT_PLANNED_PURCHASE” 您接下来计划购买什么产品? 不适用
“EVENT_SIGNUP_INTEREST” 您要报名参加某项活动吗? 不适用
“PREFERRED_SHOPPING_PLACES” 您有兴趣在哪里购物? 不适用
“FAVORITE_BRAND” 您最喜欢哪个品牌? 不适用
"TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" 您持有哪种类型的有效商业驾照? 不适用
“EVENT_BOOKING_INTEREST” 您有兴趣预订活动吗? 不适用
“DESTINATION_COUNTRY” 您的目的地是哪个国家/地区? 不适用
“DESTINATION_CITY” 您的目的地是哪个城市? 不适用
“DEPARTURE_COUNTRY” 您从哪个国家/地区出发? 不适用
“离开城市” 您从哪个城市出发? 不适用
“DEPARTURE_DATE” 您于哪一天出发? 不适用
RETURN_DATE 您的回程日期是哪一天? 不适用
“NUMBER_OF_TRAVELERS” 您要与多少人一起旅行? 不适用
TRAVEL_BUDGET 您的旅行预算是多少? 不适用
TRAVEL_ACCOMMODATION 您在旅行途中想要住在哪里? 不适用

潜在客户处理

潜在客户处理程序应使用以下 HTTP 代码进行响应:

HTTP 响应 响应正文 (JSON) 可重试错误?
200 {} 不适用
4XX {"消息:自由格式的错误文本,描述请求中存在的问题"}
5XX {"message: 间歇性可重试错误可选消息"}

重复消息

一位潜在客户不一定会交付一次,因此潜在客户 处理 webhook 时应妥善处理重复项。