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。当前产品允许在广告系列一级附加表单(而不是在广告组一级或广告一级附加)。
影响:只能在 客户端需要使用 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 收到的潜在客户之前,验证 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
此字段具有“可选”语义。如果值为 true,则将此潜在客户视为测试潜在客户。如果值为 false 或字段不存在,则将此潜在客户视为有效的生产潜在客户。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
重复的键值对元组,用于传输用户提交的数据。
|
潜在客户处理
潜在客户处理程序应使用以下 HTTP 代码进行响应:
HTTP 响应 | 响应正文 (JSON) | 可重试的错误? |
---|---|---|
200 |
{} | 不适用 |
4XX |
{"message: 自由格式的错误文本,描述请求存在的问题"} | 否 |
5XX |
{"message: 间歇性可重试错误可选消息"} | 是 |
重复消息
单个潜在客户不保证恰好传送一次,因此潜在客户处理 webhook 应该能够妥善处理重复项。