導入

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_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 格式)，例如"[phone]"。 「User Phone」 「POSTAL_CODE」 使用者的郵遞區號。 「郵遞區號」 「COMPANY_NAME」 使用者的公司名稱。 「公司名稱」 「JOB_TITLE」 使用者的職稱。 「職稱」 「WORK_EMAIL」 使用者的公司電子郵件地址。 「工作電子郵件」 「WORK_PHONE」 使用者的公司電話。 「工作電話」 「STREET_ADDRESS」 使用者的街道地址。 「街道地址」 「CITY」 使用者所在城市。 「City」 「REGION」 使用者所在區域。 「Region」 「COUNTRY」 使用者所在國家/地區。 「Country」 「VEHICLE_MODEL」 你對哪種車型感興趣？ 不適用 「VEHICLE_TYPE」 你對哪種車款感興趣？ 不適用 「PREFERRED_DEALERSHIP」 選擇您的首選經銷商 不適用 「VEHICLE_PURCHASE_TIMELINE」 你打算何時買車？ 不適用 「VEHICLE_CONDITION」 你對哪種車況感興趣？ 不適用 「VEHICLE_OWNERSHIP」 你有車嗎？ 「N/A」 「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 個位元組的整數進行處理。

待開發客戶處理

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

HTTP 回應	回應主體 (JSON)	是否可重試的錯誤？
200	{}	不適用
4XX	{"message: 自由格式錯誤文字，說明要求發生錯誤"}	否
5XX	{"message: 間歇性可回復錯誤的選用訊息"}	是

重複的聯絡人

系統無法保證單一待開發客戶會傳送一次，因此待開發客戶處理 Webhook 應妥善處理重複項目。

重點： 使用 lead_id 去除重複的待開發客戶。