導入

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;
  // 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 stage at the time of delivery.
  string lead_stage = 12 [(datapol.semantic_type) = ST_NOT_REQUIRED];
  // Lead submit time in ISO-8601 format. Ex- 2024-09-26T12:30:00Z
  string lead_submit_time = 13 [(datapol.semantic_type) = ST_NOT_REQUIRED];
}

欄位說明

欄位 說明
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 User_column_data.string_value 內容 user_column_data.column_name (已淘汰)
「FULL_NAME」 使用者全名。 「全名」
「FIRST_NAME」 使用者的名字。 「First Name」(名字)
「LAST_NAME」 使用者的姓氏。 「姓氏」
「EMAIL」 使用者的電子郵件。 「使用者電子郵件」
「PHONE_NUMBER」 使用者電話號碼，格式為 E.164，例如 "+11234567890"。 「User Phone」(使用者手機)
「PHONE_NUMBER_VERIFIED」 使用者電話號碼是否已通過驗證。 「電話號碼已驗證」
「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」 你對哪項服務感興趣？ 不適用
「OFFER」 你對哪項優惠感興趣？ 不適用
"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」 你將前往哪座城市？ 不適用
「DEPARTURE_COUNTRY」 你將從哪個國家/地區出發？ 不適用
「DEPARTURE_CITY」 你將從哪個城市出發？ 不適用
「DEPARTURE_DATE」 你的出發日期是？ 不適用
「RETURN_DATE」 你的回程日期是？ 不適用
「NUMBER_OF_TRAVELERS」 你的旅伴有幾人？ 不適用
「TRAVEL_BUDGET」 你的旅遊預算有多少？ 不適用
"TRAVEL_ACCOMMODATION" 你旅途中打算在哪裡住宿？ 不適用
asset_group_id 這個欄位只會填入最高成效廣告活動。 這表示包含待開發客戶表單的容器 ID。

用戶端必須使用 8 位元組整數進行處理。
lead_stage 這表示系統傳送待開發客戶時的階段。這個欄位有助於追蹤待開發客戶的漏斗階段 / 轉換狀態。
lead_submit_time 這表示使用者提交表單的時間戳記。以 ISO-8601 格式表示。Ex- 2024-09-26T12:30:00Z

無法辨識的欄位和向前相容性

為確保 Webhook 整合功能維持穩定，並能適應日後的強化功能，建議您設計 JSON 剖析器時，讓系統能順利忽略 Webhook 酬載中未明確取用或辨識的任何欄位，這是標準最佳做法。

重要建議：設定 JSON 剖析邏輯，只處理應用程式特別需要的欄位。請勿編寫預期有固定欄位集的程式碼，或在酬載中出現新的非預期欄位時會失敗的程式碼。

重要性：

  • 向前相容性：Google 可能會在日後的更新中，於 Webhook 酬載中新增選填欄位，以提供更豐富的資料或新功能。如果剖析器過於嚴格 (例如，遇到不明屬性就會失敗)，Google 推出這類非破壞性變更時，您的整合功能可能會中斷。
  • 簡化維護作業：只專注於您主動使用的資料點，整合程式碼會更簡單，也更容易維護。

大多數現代 JSON 剖析程式庫都提供選項，可預設忽略不明屬性，或設定為忽略不明屬性。

待開發客戶處理

待開發客戶處理人員應以下列 HTTP 程式碼回應：

HTTP 回應 回應內文 (JSON) 可重試的錯誤？
200 {} 不適用
4XX {"message: Free form error text, describing what was wrong with request"} 否
5XX {"message: Intermittent retraible error optional message"} 是

重複的聯絡人

系統不保證只會傳送一次待開發客戶資訊，因此待開發客戶處理 webhook 應能妥善處理重複資訊。