实现

POST 架构

发送到 webhook 的 POST 请求将采用 JSON 格式，并采用以下架构：

网络钩子 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” 用户的姓氏。 “姓氏” "EMAIL" 用户的电子邮件地址。 "User Email" “PHONE_NUMBER” E.164 格式的用户电话，例如"[phone]". "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” 您对哪种服务感兴趣？ 不适用 “优惠” 您对哪种优惠感兴趣？ 不适用 “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” 您的目的地是哪个城市？ 不适用 “Flight_COUNTRY” 您从哪个国家/地区出发？ 不适用 “起飞城市” 您从哪个城市出发？ 不适用 “CONVERSION_DATE” 您于哪一天出发？ 不适用 “RETURN_DATE” 您的回程日期是哪一天？ 不适用 “NUMBER_OF_TRAVELERS” 您要与多少人一起旅行？ 不适用 “TRAVEL_budget” 您的旅行预算是多少？ 不适用 “TRAVEL_ACCOMMODATION” 您在旅行途中想要住在哪里？ 不适用

潜在客户处理

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

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

重复消息

单个潜在客户不保证恰好传送一次，因此潜在客户处理 webhook 应该能够妥善处理重复项。

要点 ：使用 lead_id 对潜在客户信息进行去重处理。