導入

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。目前的產品可讓您附加含有廣告活動層級的表單 (相較於廣告群組或廣告層級附加的表單)。

影響:只能在 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 使用者欄資料.string_value content user_column_data.column_name (已淘汰)
「FULL_NAME」 使用者的全名。 「全名」
「FIRST_NAME」 使用者的名字。 「名字」
「LAST_NAME」 使用者的姓氏。 「姓氏」
"EMAIL" 使用者的電子郵件。 「使用者電子郵件」
「PHONE_NUMBER」 採用 E.164 格式的使用者電話號碼,例如"+11234567890". 「使用者電話號碼」
「POSTAL_CODE」 使用者的郵遞區號。 「郵遞區號」
「COMPANY_NAME」 使用者的公司名稱。 「公司名稱」
"JOB_TITLE" 使用者的職稱。 「職稱」
「WORK_EMAIL」 使用者的公司電子郵件地址。 「公司電子郵件」
「WORK_PHONE」 使用者的公司電話。 「公司電話」
「STREET_ADDRESS」 使用者的街道地址。 「街道地址」
「城市」 使用者所在城市。 「城市」
「區域」 使用者所在地區。 「區域」
「COUNTRY」 使用者所在的國家/地區。 「國家/地區」
VEHICLE_MODEL 你對哪種車型感興趣? 不適用
「VEHICLE_TYPE」 你對哪種車款感興趣? 不適用
「PREFERRED_DEALERSHIP」 選擇您的首選經銷商 不適用
「VEHICLE_PURCHASE_TIMELINE」 你打算何時買車? 不適用
「VEHICLE_條件」 你對哪種車況感興趣? 不適用
「VEHICLE_OWNERSHIP」 你有車嗎? 「不適用」
「VEHICLE_PAYMENT_TYPE」 你希望如何支付購車款項? 不適用
「COMPANY_SIZE」 貴公司的規模如何? 不適用
「ANNUAL_SALES」 你的年銷售額是多少? 不適用
「YEARS_IN_BUSINESS」 你在這行待了多少年? 不適用
「JOB_DEPARTMENT」 你任職的部門是? 不適用
「JOB_ROLE」 你的職務是? 不適用
「EDUCATION_PROGRAM」 你對哪門學程感興趣? 不適用
「EDUCATION_COURSE」 你對哪門課程感興趣? 不適用
「產品」 你對哪項產品感興趣? 不適用
「SERVICE」 你對哪項服務感興趣? 不適用
「OFFER」 你對哪項優惠感興趣? 不適用
「類別」 你對哪個類別感興趣? 不適用
「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」 你將前往哪座城市? 不適用
「出發國家/地區」 你將從哪個國家/地區出發? 不適用
「出發城市」 你將從哪個城市出發? 不適用
「出發日期」 你的出發日期是? 不適用
「RETURN_DATE」 你的回程日期是? 不適用
「NUMBER_OF_TRAVELERS」 你的旅伴有幾人? 不適用
「TRAVEL_BUDGET」 你的旅遊預算有多少? 不適用
「TRAVEL_ACCOMMODATION」 你旅途中打算在哪裡住宿? 不適用

待開發客戶處理

待開發客戶處理常式應以下列 HTTP 代碼回應:

HTTP 回應 回應主體 (JSON) 可重試的錯誤嗎?
200 {} 不適用
4XX {"message: 任意形式錯誤文字,描述要求有誤的部分"}
5XX {"message: 間歇性可迴轉錯誤 (選用)"}

重複項目

一個待開發客戶不保證一定會傳送一次,因此待開發客戶處理 Webhook 應妥善處理重複的問題。