POST 架构
发送至网络钩子的 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;
// 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 |
唯一字符串，用于标识给定潜在客户。
处理建议：用于对接收的潜在客户进行去重。此字段在所有表单中都是唯一的。报告与特定潜在客户相关的问题时需要使用此 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 |
广告客户为每个表单配置的密钥。
处理建议：在通过网络钩子处理接收的潜在客户之前，验证 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
此字段具有“可选”语义。如果值为 true，则将此潜在客户视为测试潜在客户。如果值为 false 或字段不存在，则将此潜在客户视为有效的正式版潜在客户。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
重复的键值对元组，用于传输用户提交的数据。
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
系统仅会为效果最大化广告系列填充此字段。
表示包含潜在客户表单的容器 ID。
客户端需要使用 8 字节整数进行处理。 |
潜在客户处理
潜在客户处理程序应作出响应，并返回以下 HTTP 代码：
| HTTP 响应 | 响应正文 (JSON) | 可重试的错误？ |
|---|---|---|
200 |
{} | 不适用 |
4XX |
{"message: Free form error text, describing what was wrong with request"} | 否 |
5XX |
{"message: Intermittent retraible error optional message"} | 是 |
重复消息
同一个潜在客户不保证仅准确地提交一次，因此潜在客户处理网络钩子应合理处理重复项。