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