สคีมา POST
คำขอ POST ที่ส่งไปยัง Webhook จะเป็นรูปแบบ 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 | สตริงที่ไม่ซ้ำกันซึ่งระบุโอกาสในการขายหนึ่งๆ การจัดการคําแนะนํา: ใช้เพื่อกรองโอกาสในการขายที่ซ้ำกันออก ซึ่งจะไม่ซ้ำกันในทุกแบบฟอร์มทั้งหมด คุณต้องใช้รหัสนี้เมื่อรายงานปัญหาที่เกี่ยวข้องกับโอกาสในการขายที่เฉพาะเจาะจง | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| api_version | เวอร์ชัน API ของสคีมาโอกาสในการขายนี้ ระบบจะใช้ค่านี้เมื่อย้ายข้อมูลไปยังสคีมาใหม่ และคุณสามารถละเว้นได้ในตอนนี้ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| form_id | รหัสที่ไม่ซ้ำกันสําหรับแบบฟอร์มแต่ละรายการที่กําหนดค่าใน Google Ads ผลิตภัณฑ์ปัจจุบันอนุญาตให้แนบแบบฟอร์มกับระดับแคมเปญ (เทียบกับระดับกลุ่มโฆษณาหรือระดับโฆษณา) ผลกระทบ: คุณสามารถแบ่งกลุ่มโอกาสในการขายได้ที่ระดับ  ไคลเอ็นต์ต้องใช้จำนวนเต็ม 8 ไบต์เพื่อประมวลผล | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| campaign_id | รหัสแคมเปญ Google Ads หรือรหัสรายการโฆษณา (Display & Video 360) ของโฆษณาแบบกรอกฟอร์มที่แนบมา ไคลเอ็นต์ต้องใช้จำนวนเต็ม 8 ไบต์เพื่อประมวลผล | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| adgroup_id | ระบบจะใช้รหัสกลุ่มโฆษณา Google Ads เพื่อแยกความแตกต่างของกลุ่มโฆษณาที่เฉพาะเจาะจงในแคมเปญ (ใช้ได้กับโอกาสในการขายจากโฆษณาวิดีโอและโฆษณา Discovery เท่านั้น) ไคลเอ็นต์ต้องใช้จำนวนเต็ม 8 ไบต์เพื่อประมวลผล | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| creative_id | รหัสครีเอทีฟโฆษณา Google Ads ใช้เพื่อแยกครีเอทีฟโฆษณาที่เฉพาะเจาะจงในกลุ่มโฆษณา (ใช้ได้กับโอกาสในการขายจากโฆษณาวิดีโอและโฆษณา Discovery เท่านั้น) ไคลเอ็นต์ต้องใช้จำนวนเต็ม 8 ไบต์เพื่อประมวลผล | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gcl_id | รหัสคลิกของ Google ซึ่งเป็นพารามิเตอร์ที่ไม่ซ้ำกันซึ่งใช้ติดตามการคลิกโฆษณาแต่ละครั้ง | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| google_key | คีย์ที่ผู้ลงโฆษณากําหนดค่าไว้กับแบบฟอร์มแต่ละรายการ คําแนะนําในการจัดการ: ก่อนประมวลผลโอกาสในการขายที่ได้รับผ่าน Webhook การยืนยัน  | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is_test | ฟิลด์นี้มีความหมายเป็น "ไม่บังคับ" หากค่าเป็น "จริง" ให้ถือว่าโอกาสในการขายนี้เป็นโอกาสในการขายทดสอบ หากค่าเป็นเท็จหรือไม่มีฟิลด์ ให้ถือว่าโอกาสในการขายนี้เป็นโอกาสในการขายเวอร์ชันที่ใช้งานจริงที่ถูกต้อง | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| user_column_data | คู่คีย์-ค่าที่ซ้ำกันซึ่งส่งข้อมูลที่ผู้ใช้ส่ง 
 
 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| asset_group_id | ระบบจะป้อนข้อมูลในช่องนี้สําหรับแคมเปญ Performance Max เท่านั้น
      ข้อมูลนี้ระบุรหัสคอนเทนเนอร์ที่มีโฆษณาแบบกรอกฟอร์ม ไคลเอ็นต์ต้องใช้จำนวนเต็ม 8 ไบต์เพื่อประมวลผล | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lead_stage | ข้อมูลนี้แสดงถึงระยะของโอกาสในการขาย ณ เวลาที่ส่งโอกาสในการขาย ช่องนี้มีประโยชน์ในการติดตามระยะ Funnel / สถานะ Conversion ของโอกาสในการขาย | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lead_submit_time | ข้อมูลนี้แสดงการประทับเวลาที่ผู้ใช้ส่งแบบฟอร์ม โดยแสดงในรูปแบบ ISO-8601 เช่น 2024-09-26T12:30:00Z | 
ฟิลด์ที่ไม่รู้จักและความเข้ากันได้ในอนาคต
แนวทางปฏิบัติแนะนำมาตรฐานคือการออกแบบโปรแกรมแยกวิเคราะห์ JSON ให้ละเว้นช่องใดๆ ในเพย์โหลดของเว็บฮุคที่ระบบไม่ได้ใช้หรือจดจำอย่างชัดแจ้ง เพื่อให้การผสานรวมเว็บฮุคยังคงมีประสิทธิภาพและสามารถปรับให้เข้ากับการเพิ่มประสิทธิภาพในอนาคต
คําแนะนําที่สําคัญ: กําหนดค่าตรรกะการแยกวิเคราะห์ JSON ให้ประมวลผลเฉพาะฟิลด์ที่จําเป็นสําหรับแอปพลิเคชันของคุณเท่านั้น อย่าเขียนโค้ดที่คาดหวังชุดฟิลด์ที่แน่นอนหรือจะใช้งานไม่ได้หากมีฟิลด์ใหม่ที่ไม่คาดคิดในเพย์โหลด
ความสำคัญของเรื่องนี้:
- ความเข้ากันได้ในอนาคต: Google อาจเพิ่มช่องใหม่ที่ไม่บังคับลงในเพย์โหลดของ Webhook ในการอัปเดตในอนาคตเพื่อให้ข้อมูลหรือฟีเจอร์ใหม่ๆ ที่สมบูรณ์ยิ่งขึ้น หากโปรแกรมแยกวิเคราะห์ของคุณเข้มงวดเกินไป (เช่น ดำเนินการกับพร็อพเพอร์ตี้ที่ไม่รู้จักไม่สำเร็จ) การผสานรวมอาจใช้งานไม่ได้เมื่อ Google เปิดตัวการเปลี่ยนแปลงที่ไม่ก่อให้เกิดปัญหาดังกล่าว
- การบำรุงรักษาที่ง่ายขึ้น: การมุ่งเน้นเฉพาะจุดข้อมูลที่ใช้งานอยู่จะช่วยให้โค้ดการผสานรวมยังคงเรียบง่ายและบำรุงรักษาได้ง่ายขึ้น
ไลบรารีการแยกวิเคราะห์ JSON สมัยใหม่ส่วนใหญ่มีตัวเลือกในการละเว้นพร็อพเพอร์ตี้ที่ไม่รู้จักโดยค่าเริ่มต้น หรือสามารถกําหนดค่าให้ทําเช่นนั้นได้
การจัดการโอกาสในการขาย
แฮนเดิลโอกาสในการขายควรตอบกลับด้วยรหัส HTTP ต่อไปนี้
| การตอบกลับ HTTP | เนื้อหาการตอบกลับ (JSON) | ข้อผิดพลาดที่ลองอีกครั้งได้ไหม | 
|---|---|---|
| 200 | {} | ไม่มี | 
| 4XX | {"message: ข้อความแสดงข้อผิดพลาดแบบอิสระที่อธิบายถึงสิ่งที่ไม่ถูกต้องเกี่ยวกับคำขอ"} | ไม่ | 
| 5XX | {"message: Intermittent retraible error optional message"} | ใช่ | 
รายการซ้ำ
ระบบไม่รับประกันว่าระบบจะนำส่งโอกาสในการขายรายการเดียวเพียงครั้งเดียว ดังนั้นเว็บฮุคสำหรับจัดการโอกาสในการขายควรจัดการรายการที่ซ้ำกันอย่างเหมาะสม