طرحواره پست
درخواست POST ارسال شده به webhook در قالب JSON با طرحواره زیر خواهد بود:
بار داده پروتو وبهوک
// 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 | شناسه منحصر به فرد برای هر فرم پیکربندی شده در گوگل ادز. محصول فعلی امکان پیوست کردن فرم با سطح کمپین را فراهم میکند (در مقابل پیوست کردن در گروه تبلیغاتی یا سطوح تبلیغاتی). پیامدها: سرنخها را فقط میتوان در سطح کلاینتها برای پردازش باید از عدد صحیح ۸ بایتی استفاده کنند. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id | شناسه کمپین گوگل ادز یا شناسه ردیف آیتم (نمایش و ویدیوی ۳۶۰) فرم سرنخ پیوست شده. کلاینتها برای پردازش باید از یک عدد صحیح ۸ بایتی استفاده کنند. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id | شناسه گروه تبلیغاتی گوگل ادز برای تشخیص گروه تبلیغاتی خاص در کمپین استفاده میشود. (فقط برای سرنخهای حاصل از تبلیغات ویدیویی و اکتشافی موجود است) کلاینتها برای پردازش باید از یک عدد صحیح ۸ بایتی استفاده کنند. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id | شناسه خلاقیت گوگل ادز برای تشخیص خلاقیت خاص در گروه تبلیغاتی استفاده میشود. (فقط برای سرنخهای حاصل از تبلیغات ویدیویی و اکتشافی موجود است) کلاینتها برای پردازش باید از یک عدد صحیح ۸ بایتی استفاده کنند. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id | شناسه کلیک گوگل ، یک پارامتر منحصر به فرد که برای ردیابی هر کلیک روی یک تبلیغ استفاده میشود. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key | کلیدی که توسط تبلیغکننده با هر فرم پیکربندی شده است. توصیههای مدیریتی: قبل از پردازش سرنخ دریافتی از طریق وبهوک، اعتبارسنجی | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test | این فیلد معنای «اختیاری» دارد. اگر مقدار آن درست باشد، این سرنخ را به عنوان سرنخ آزمایشی در نظر بگیرید. اگر مقدار آن نادرست باشد یا اگر فیلدی وجود نداشته باشد، این سرنخ را به عنوان سرنخ تولید معتبر در نظر بگیرید. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data | یک تاپل کلید-مقدار تکراری که دادههای ارسالی کاربر را منتقل میکند.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id | این فیلد فقط برای کمپینهای Performance-Max پر میشود. این نشان دهنده شناسه کانتینری است که فرم سرنخ (lead form) در آن قرار دارد. کلاینتها برای پردازش باید از یک عدد صحیح ۸ بایتی استفاده کنند. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage | این فیلد، مرحله سرنخ (لید) را در زمان تحویل سرنخ نشان میدهد. این فیلد در ردیابی مرحله قیف فروش / وضعیت تبدیل یک سرنخ مفید است. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time | این نشان دهندهی مهر زمانی است که کاربر فرم را ارسال کرده است. این مهر در قالب ISO-8601 نمایش داده میشود. مثال: 2024-09-26T12:30:00Z |
فیلدهای ناشناخته و سازگاری رو به جلو
برای اطمینان از اینکه ادغام وبهوک شما قوی باقی میماند و میتواند با پیشرفتهای آینده سازگار شود، بهترین روش استاندارد این است که تجزیهکننده JSON خود را طوری طراحی کنید که به طرز ماهرانهای هر فیلدی را در بار داده وبهوک که سیستم شما صریحاً مصرف نمیکند یا نمیشناسد، نادیده بگیرد.
توصیه کلیدی: منطق تجزیه JSON خود را طوری پیکربندی کنید که فقط فیلدهایی را که به طور خاص برای برنامه خود نیاز دارید پردازش کند. کدی ننویسید که انتظار مجموعهای ثابت از فیلدها را داشته باشد یا در صورت وجود فیلدهای جدید و غیرمنتظره در payload، با شکست مواجه شود.
چرا این مهم است:
- سازگاری رو به جلو: گوگل ممکن است در بهروزرسانیهای آینده فیلدهای جدید و اختیاری را به بار دادهی وبهوک اضافه کند تا دادههای غنیتر یا ویژگیهای جدید ارائه دهد. اگر تجزیهگر شما بیش از حد دقیق باشد (مثلاً روی ویژگیهای ناشناخته از کار بیفتد)، ادغام شما میتواند زمانی که چنین تغییرات غیرقابلانکار توسط گوگل اعمال میشود، با مشکل مواجه شود.
- نگهداری ساده: با تمرکز صرف بر روی نقاط دادهای که به طور فعال استفاده میکنید، کد یکپارچهسازی شما سادهتر و نگهداری آن آسانتر میشود.
اکثر کتابخانههای مدرن تجزیه JSON گزینههایی را برای نادیده گرفتن ویژگیهای ناشناخته به طور پیشفرض ارائه میدهند یا میتوانند برای انجام این کار پیکربندی شوند.
مدیریت سرب
گردانندگان سرنخ (Lead Handlers) باید با کدهای HTTP زیر پاسخ دهند:
| پاسخ HTTP | متن پاسخ (JSON) | خطای قابل تکرار؟ |
|---|---|---|
200 | {} | ناموجود |
4XX | {"پیام: متن خطای فرم آزاد، توضیح مشکل درخواست"} | خیر |
5XX | {"پیام: پیام اختیاری خطای قابل بازیابی متناوب"} | بله |
تکراریها
تضمینی وجود ندارد که یک سرنخ دقیقاً یک بار تحویل داده شود، از این رو، وبهوک مدیریت سرنخ باید به خوبی با موارد تکراری برخورد کند.