Giản đồ POST
Yêu cầu POST được gửi đến webhook sẽ ở định dạng JSON với giản đồ sau:
Tải trọng 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];
}
Phần mô tả về trường
| Trường | Mô tả | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id |
Chuỗi duy nhất xác định một khách hàng tiềm năng cụ thể.
Xử lý đề xuất: Sử dụng đề xuất này để loại bỏ khách hàng tiềm năng trùng lặp mà bạn nhận được. Mã này sẽ là duy nhất trên tất cả các biểu mẫu. Khi báo cáo vấn đề liên quan đến một khách hàng tiềm năng cụ thể, bạn sẽ phải cung cấp mã nhận dạng này. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
Phiên bản API mà giản đồ khách hàng tiềm năng này thuộc về. Thao tác này sẽ được dùng khi di chuyển sang một giản đồ mới và bạn có thể bỏ qua thao tác này ngay bây giờ. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id |
Mã nhận dạng riêng biệt cho từng biểu mẫu được định cấu hình trong Google Ads. Sản phẩm hiện tại cho phép đính kèm biểu mẫu ở cấp chiến dịch (thay vì đính kèm ở cấp nhóm quảng cáo hoặc quảng cáo).
Hậu quả: Bạn chỉ có thể phân đoạn khách hàng tiềm năng ở cấp Khách hàng cần sử dụng số nguyên 8 byte để xử lý. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id |
Mã chiến dịch Google Ads hoặc mã mục hàng (Display & Video 360) của biểu mẫu khách hàng tiềm năng được đính kèm.
Khách hàng cần sử dụng số nguyên 8 byte để xử lý. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id |
Mã nhóm quảng cáo trên Google Ads được dùng để phân biệt nhóm quảng cáo cụ thể trong chiến dịch. (Chỉ dành cho khách hàng tiềm năng từ quảng cáo dạng video và quảng cáo Khám phá)
Khách hàng cần sử dụng số nguyên 8 byte để xử lý. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id |
Mã mẫu quảng cáo Google Ads được dùng để phân biệt mẫu quảng cáo cụ thể trong nhóm quảng cáo. (Chỉ dành cho khách hàng tiềm năng từ quảng cáo dạng video và quảng cáo Khám phá)
Khách hàng cần sử dụng số nguyên 8 byte để xử lý. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id |
Mã lượt nhấp của Google, một tham số duy nhất dùng để theo dõi từng lượt nhấp vào quảng cáo. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key |
Khoá do nhà quảng cáo định cấu hình cho từng biểu mẫu.
Cách xử lý đề xuất: Trước khi xử lý khách hàng tiềm năng nhận được qua webhook, hãy xác thực |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
Trường này có ngữ nghĩa "không bắt buộc". Nếu giá trị là true, hãy coi khách hàng tiềm năng này là khách hàng tiềm năng thử nghiệm. Nếu giá trị là false hoặc nếu trường không có, hãy coi khách hàng tiềm năng này là khách hàng tiềm năng hợp lệ để sản xuất. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
Một bộ khoá-giá trị lặp lại truyền dữ liệu do người dùng gửi.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
Trường này chỉ được điền sẵn cho chiến dịch Tối đa hoá hiệu suất.
Đây là mã nhận dạng vùng chứa chứa biểu mẫu khách hàng tiềm năng.
Khách hàng cần sử dụng số nguyên 8 byte để xử lý. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage |
Đây là giai đoạn khách hàng tiềm năng tại thời điểm phân phối khách hàng tiềm năng. Trường này hữu ích trong việc theo dõi giai đoạn trên phễu / trạng thái chuyển đổi của khách hàng tiềm năng. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time |
Đây là dấu thời gian cho biết thời điểm người dùng gửi biểu mẫu. Được biểu thị ở định dạng ISO-8601. Ex- 2024-09-26T12:30:00Z |
Các trường không được nhận dạng và khả năng tương thích trong tương lai
Để đảm bảo chế độ tích hợp webhook của bạn vẫn mạnh mẽ và có thể thích ứng với các tính năng nâng cao trong tương lai, bạn nên thiết kế trình phân tích cú pháp JSON để bỏ qua một cách linh hoạt mọi trường trong tải trọng webhook mà hệ thống của bạn không sử dụng hoặc nhận dạng một cách rõ ràng.
Đề xuất chính: Định cấu hình logic phân tích cú pháp JSON để chỉ xử lý các trường mà bạn cần cụ thể cho ứng dụng của mình. Đừng viết mã dự kiến một tập hợp trường cố định hoặc sẽ gặp lỗi nếu có các trường mới, không mong muốn trong tải trọng.
Tại sao điều này lại quan trọng:
- Khả năng tương thích về sau: Google có thể thêm các trường mới (không bắt buộc) vào tải trọng webhook trong các bản cập nhật sau này để cung cấp dữ liệu phong phú hơn hoặc các tính năng mới. Nếu trình phân tích cú pháp của bạn quá nghiêm ngặt (ví dụ: không thành công đối với các thuộc tính không xác định), thì quá trình tích hợp của bạn có thể bị gián đoạn khi Google triển khai những thay đổi không gây lỗi như vậy.
- Bảo trì đơn giản: Bằng cách chỉ tập trung vào những điểm dữ liệu mà bạn đang sử dụng, mã tích hợp của bạn sẽ đơn giản và dễ duy trì hơn.
Hầu hết các thư viện phân tích cú pháp JSON hiện đại đều cung cấp các lựa chọn để bỏ qua các thuộc tính không xác định theo mặc định hoặc có thể được định cấu hình để làm như vậy.
Xử lý khách hàng tiềm năng
Trình xử lý khách hàng tiềm năng phải phản hồi bằng các mã HTTP sau:
| Phản hồi HTTP | Nội dung phản hồi (JSON) | Lỗi có thể thử lại? |
|---|---|---|
200 |
{} | Không áp dụng |
4XX |
{"message: Free form error text, describing what was wrong with request"} | Không |
5XX |
{"message: Intermittent retraible error optional message"} | Có |
Liên hệ trùng lặp
Không đảm bảo rằng một khách hàng tiềm năng duy nhất sẽ được phân phối chính xác một lần, do đó, webhook xử lý khách hàng tiềm năng phải xử lý các trường hợp trùng lặp một cách phù hợp.