สคีมา POST
คำขอ POST ที่ส่งไปยังเว็บฮุกจะเป็นรูปแบบ JSON ที่มีสคีมาต่อไปนี้
เพย์โหลด 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 Click ID ซึ่งเป็นพารามิเตอร์ที่ไม่ซ้ำกันที่ใช้เพื่อติดตามการคลิกโฆษณาแต่ละครั้ง | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 อาจเพิ่มฟิลด์ใหม่ที่ไม่บังคับลงในเพย์โหลดของเว็บฮุก ในการอัปเดตในอนาคตเพื่อมอบข้อมูลที่สมบูรณ์ยิ่งขึ้นหรือฟีเจอร์ใหม่ๆ หากตัวแยกวิเคราะห์เข้มงวดเกินไป (เช่น ไม่ทำงานกับพร็อพเพอร์ตี้ที่ไม่รู้จัก) การผสานรวมอาจหยุดทำงานเมื่อ 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"} | ใช่ |
รายการซ้ำ
ระบบไม่รับประกันว่าจะส่งผู้มีโอกาสเป็นลูกค้า 1 รายเพียงครั้งเดียวเท่านั้น ดังนั้นเว็บฮุคการจัดการผู้มีโอกาสเป็นลูกค้าจึงควรจัดการรายการที่ซ้ำกันอย่างเหมาะสม