پیاده سازی

طرحواره پست

درخواست 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 شناسه منحصر به فرد برای هر فرم پیکربندی شده در گوگل ادز. محصول فعلی امکان پیوست کردن فرم با سطح کمپین را فراهم می‌کند (در مقابل پیوست کردن در گروه تبلیغاتی یا سطوح تبلیغاتی).

پیامدها: سرنخ‌ها را فقط می‌توان در سطح form_id (یعنی در سطح کمپین) برش داد.

کلاینت‌ها برای پردازش باید از عدد صحیح ۸ بایتی استفاده کنند.

campaign_id شناسه کمپین گوگل ادز یا شناسه ردیف آیتم (نمایش و ویدیوی ۳۶۰) فرم سرنخ پیوست شده.

کلاینت‌ها برای پردازش باید از یک عدد صحیح ۸ بایتی استفاده کنند.

adgroup_id شناسه گروه تبلیغاتی گوگل ادز برای تشخیص گروه تبلیغاتی خاص در کمپین استفاده می‌شود. (فقط برای سرنخ‌های حاصل از تبلیغات ویدیویی و اکتشافی موجود است)

کلاینت‌ها برای پردازش باید از یک عدد صحیح ۸ بایتی استفاده کنند.

creative_id شناسه خلاقیت گوگل ادز برای تشخیص خلاقیت خاص در گروه تبلیغاتی استفاده می‌شود. (فقط برای سرنخ‌های حاصل از تبلیغات ویدیویی و اکتشافی موجود است)

کلاینت‌ها برای پردازش باید از یک عدد صحیح ۸ بایتی استفاده کنند.

gcl_id شناسه کلیک گوگل ، یک پارامتر منحصر به فرد که برای ردیابی هر کلیک روی یک تبلیغ استفاده می‌شود.
google_key کلیدی که توسط تبلیغ‌کننده با هر فرم پیکربندی شده است.

توصیه‌های مدیریتی: قبل از پردازش سرنخ دریافتی از طریق وب‌هوک، اعتبارسنجی google_key مشابه پیکربندی در گوگل ادز است تا اطمینان بیشتری از اعتبار سرنخ حاصل شود. این کلید را محرمانه نگه دارید و در صورت وجود دلیلی مبنی بر اینکه این کلید به طور گسترده فاش شده است، آن را در گوگل ادز به‌روزرسانی کنید.

is_test این فیلد معنای «اختیاری» دارد. اگر مقدار آن درست باشد، این سرنخ را به عنوان سرنخ آزمایشی در نظر بگیرید. اگر مقدار آن نادرست باشد یا اگر فیلدی وجود نداشته باشد، این سرنخ را به عنوان سرنخ تولید معتبر در نظر بگیرید.
user_column_data یک تاپل کلید-مقدار تکراری که داده‌های ارسالی کاربر را منتقل می‌کند.
  • user_column_data.column_id : نوع داده ارسال شده توسط کاربر.
  • User_column_data.column_value : برای هر نوع داده، یک نوع مقدار بسته به نوع داده وجود خواهد داشت. همه انواع داده فعلی ما دارای مقدار user_column_data.string_value هستند.
  • user_column_data.column_name : متن خوانا برای انسان از نوع داده‌ای که توسط کاربر ارسال می‌شود. این فیلد ممکن است همیشه پر نشود، به جای آن column_id استفاده کنید.
شناسه ستون کاربر محتوای User_column_data.string_value user_column_data.column_name (منسوخ شده)
"نام_کامل" نام کامل کاربر. «نام کامل»
"نام_اول" نام کاربری «نام کوچک»
"نام_خانوادگی" نام خانوادگی کاربر. «نام خانوادگی»
«ایمیل» ایمیل کاربر. «ایمیل کاربر»
"شماره_تلفن" شماره تلفن کاربر با فرمت E.164 ، مثلاً "+11234567890" . «تلفن کاربر»
«شماره_تلفن_تأیید شد» آیا شماره تلفن کاربر تأیید شده است یا خیر. «شماره تلفن تأیید شد»
"کد پستی" کد پستی کاربر. «کد پستی»
"نام_شرکت" نام شرکت کاربر. «نام شرکت»
«عنوان شغلی» عنوان شغلی کاربر. «عنوان شغلی»
«ایمیل کاری» ایمیل کاری کاربر «ایمیل کاری»
«تلفن_کار» تلفن محل کار کاربر «تلفن محل کار»
«آدرس خیابان» آدرس خیابان کاربر. «آدرس خیابان»
«شهر» شهر کاربر. «شهر»
"منطقه" منطقه کاربر. «منطقه»
"کشور" کشور کاربر. «کشور»
"مدل_خودرو" به کدام مدل علاقه دارید؟ ناموجود
"نوع_خودرو" به کدام نوع وسیله نقلیه علاقه دارید؟ ناموجود
"نمایندگی_ترجیحی" نمایندگی مورد نظر خود را انتخاب کنید ناموجود
«جدول زمانی خرید خودرو» چه زمانی قصد خرید وسیله نقلیه دارید؟ ناموجود
«وضعیت_خودرو» به چه نوع وضعیت خودرو علاقه دارید؟ ناموجود
«مالکیت_خودرو» آیا شما صاحب وسیله نقلیه هستید؟ «نامشخص»
"نوع_پرداخت_وسیله_نقلیه" به کدام گزینه مالکیت خودرو علاقه‌مند هستید؟ ناموجود
"اندازه_شرکت" شرکت شما چه اندازه‌ای دارد؟ ناموجود
«فروش_سالانه» حجم فروش سالانه شما چقدر است؟ ناموجود
«سال‌ها فعالیت» چند سال است که در کسب و کار هستید؟ ناموجود
«بخش_شغلی» بخش کاری شما چیست؟ ناموجود
«نقش_شغلی» نقش شغلی شما چیست؟ ناموجود
«برنامه_آموزشی» به کدام برنامه علاقه دارید؟ ناموجود
«دوره_آموزشی» به کدام دوره علاقه دارید؟ ناموجود
«محصول» به کدام محصول علاقه دارید؟ ناموجود
«خدمات» به کدام سرویس علاقه‌مند هستید؟ ناموجود
«پیشنهاد» به کدام پیشنهاد علاقه‌مند هستید؟ ناموجود
«دسته‌بندی» به کدام دسته علاقه دارید؟ ناموجود
"روش_تماس_ترجیحی" روش تماس دلخواه خود را انتخاب کنید ناموجود
"مکان_ترجیحی" مکان مورد نظر خود را انتخاب کنید ناموجود
"زمان_ترجیحی_تماس" بهترین زمان برای تماس با شما چه زمانی است؟ ناموجود
«جدول زمانی خرید» چه زمانی قصد خرید دارید؟ ناموجود
«سال‌ها تجربه» چند سال سابقه کار دارید؟ ناموجود
«شغل_صنعت» در چه صنعتی فعالیت دارید؟ ناموجود
"سطح_آموزش" بالاترین سطح تحصیلات شما چیست؟ ناموجود
"نوع_ویژگی" به دنبال چه نوع ملکی هستید؟ ناموجود
«کمک_هدف_مشاور_املاک» در چه مواردی به کمک مشاور املاک نیاز دارید؟ ناموجود
«ملک_جامعه» به چه انجمنی علاقه دارید؟ ناموجود
"محدوده قیمت" دنبال چه محدوده قیمتی هستید؟ ناموجود
«تعداد_اتاق_خواب‌ها» دنبال چند اتاق خواب هستید؟ ناموجود
"ملک_مبله" آیا به دنبال ملکی با امکانات کامل هستید؟ ناموجود
«دارایی_مجاز_حیوانات_خانگی» آیا به دنبال ملک‌هایی هستید که اجازه ورود حیوانات خانگی را می‌دهند؟ ناموجود
«خرید_برنامه_ریزی_شده_بعدی» محصول بعدی که قصد خرید آن را دارید چیست؟ ناموجود
«رویداد_ثبت_علاقه» آیا مایل به ثبت نام در یک رویداد هستید؟ ناموجود
«مکان‌های_خرید_ترجیحی» به خرید از کجا علاقه دارید؟ ناموجود
«برند_مورد_علاقه» برند مورد علاقه شما چیست؟ ناموجود
"نوع مجوز حمل و نقل تجاری" چه نوع مجوز تجاری معتبری دارید؟ ناموجود
«رزرو_رویداد_علاقه‌مندی» آیا به رزرو رویداد علاقه دارید؟ ناموجود
"کشور_مقصد" کشور مقصد شما کدام است؟ ناموجود
«شهر_مقصد» شهر مقصد شما کدام است؟ ناموجود
«کشور مبدا» کشور مبدا شما کجاست؟ ناموجود
«شهر_حرکت» شهر مبدا شما کجاست؟ ناموجود
"تاریخ_حرکت" تاریخ اعزام شما چه زمانی است؟ ناموجود
"تاریخ_بازگشت" تاریخ برگشتت کیه؟ ناموجود
«تعداد_مسافران» با چند نفر سفر می‌کنید؟ ناموجود
«بودجه سفر» بودجه سفر شما چقدر است؟ ناموجود
«مسافرت_اقامت» در طول سفرتان کجا می‌خواهید اقامت کنید؟ ناموجود
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 {"پیام: پیام اختیاری خطای قابل بازیابی متناوب"} بله

تکراری‌ها

تضمینی وجود ندارد که یک سرنخ دقیقاً یک بار تحویل داده شود، از این رو، وب‌هوک مدیریت سرنخ باید به خوبی با موارد تکراری برخورد کند.