POST 結構定義
傳送到 Webhook 的 POST 要求會採用 JSON 格式,並採用以下結構定義:
Webhook 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 不得與「所有」表單重複。回報與特定待開發客戶相關的問題時,需要提供這個 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 應妥善處理重複的問題。