التنفيذ

مخطط POST

سيكون طلب POST المُرسَل إلى Webhook بتنسيق JSON مع المخطّط التالي:

حِمل 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];
}

وصف الحقل

الحقل الوصف
lead_id سلسلة فريدة تحدّد عميلاً محتملاً معيّنًا.

التعامل مع الاقتراح: استخدِم هذا الحقل لإزالة تكرار العملاء المحتملين الذين تم تلقّيهم. سيكون هذا المعرّف فريدًا في جميع النماذج. عند الإبلاغ عن مشاكل متعلّقة بعميل محتمل معيّن، سيكون هذا المعرّف مطلوبًا.

api_version تمثّل هذه السمة إصدار واجهة برمجة التطبيقات الذي ينتمي إليه مخطط بيانات العملاء المحتملين هذا. سيتم استخدام هذا الحقل عند نقل البيانات إلى مخطط جديد، ويمكن تجاهله في الوقت الحالي.
form_id المعرّف الفريد لكل نموذج تم إعداده في "إعلانات Google". يسمح المنتج الحالي بإرفاق نموذج على مستوى الحملة (بدلاً من إرفاقه على مستوى المجموعة الإعلانية أو الإعلان).

الآثار المترتبة: لا يمكن تقسيم العملاء المحتملين إلا على مستوى form_id (أي على مستوى الحملة).

يجب أن يستخدم العملاء عددًا صحيحًا من 8 بايتات للمعالجة.

campaign_id رقم تعريف حملة "إعلانات Google" أو رقم تعريف عنصر الحملة (مساحة العرض والفيديو 360) لنموذج بيانات العميل المحتمل المرفق.

يجب أن يستخدم العملاء عددًا صحيحًا من 8 بايت للمعالجة.

adgroup_id يُستخدَم رقم تعريف المجموعة الإعلانية على "إعلانات Google" للتمييز بين المجموعات الإعلانية المحدّدة في الحملة. (متاحة فقط للعملاء المحتملين من إعلانات الفيديو و"الإعلانات أثناء التصفّح")

يجب أن يستخدم العملاء عددًا صحيحًا من 8 بايت للمعالجة.

creative_id يُستخدَم رقم تعريف تصميم الإعلان على "إعلانات Google" للتمييز بين تصميم الإعلان المحدّد في المجموعة الإعلانية. (متاحة فقط للعملاء المحتملين من إعلانات الفيديو و"الإعلانات أثناء التصفّح")

يجب أن يستخدم العملاء عددًا صحيحًا من 8 بايت للمعالجة.

gcl_id معرّف النقرة من Google: هو مَعلمة فريدة تُستخدَم لتتبُّع كل نقرة على إعلان.
google_key مفتاح يحدّده المعلِن مع كل نموذج.

اقتراح بشأن التعامل مع المشكلة: قبل معالجة عميل محتمل تم تلقّيه عبر Webhook، يجب التأكّد من أنّ google_key هو نفسه الذي تم إعداده في "إعلانات Google" لزيادة الثقة في صحة بيانات العميل المحتمل. يجب الحفاظ على سرية هذا المفتاح وتعديله في "إعلانات Google" إذا كان هناك سبب يدعو إلى الاعتقاد بأنّه قد تم تسريبه على نطاق واسع.

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.column_id محتوى User_column_data.string_value user_column_data.column_name (متوقّفة نهائيًا)
"FULL_NAME" اسم المستخدم الكامل. "الاسم الكامل"
"FIRST_NAME" الاسم الأول للمستخدِم. "الاسم الأول"
"LAST_NAME" اسم العائلة للمستخدِم. "اسم العائلة"
"البريد الإلكتروني" عنوان البريد الإلكتروني للمستخدِم. "البريد الإلكتروني للمستخدم"
"PHONE_NUMBER" رقم هاتف المستخدم بتنسيق E.164، على سبيل المثال "+11234567890". "هاتف المستخدم"
"PHONE_NUMBER_VERIFIED" تُستخدَم لتحديد ما إذا تم إثبات ملكية رقم هاتف المستخدم. "تم تأكيد رقم الهاتف"
"POSTAL_CODE" الرمز البريدي للمستخدم "الرمز البريدي"
"COMPANY_NAME" اسم شركة المستخدم "اسم الشركة"
"JOB_TITLE" تمثّل هذه السمة المسمى الوظيفي للمستخدم. "المسمى الوظيفي"
"WORK_EMAIL" عنوان البريد الإلكتروني المخصّص للعمل الخاص بالمستخدم "البريد الإلكتروني الخاص بالعمل"
"WORK_PHONE" رقم هاتف العمل الخاص بالمستخدم "هاتف العمل"
"STREET_ADDRESS" عنوان شارع المستخدِم. "عنوان الشارع"
"CITY" مدينة المستخدِم "المدينة"
"المنطقة" منطقة المستخدم "المنطقة"
"COUNTRY" بلد المستخدم "البلد"
VEHICLE_MODEL ما هو الطراز الذي يهمك؟ لا ينطبق
"VEHICLE_TYPE" ما نوع المركبة التي تهمك؟ لا ينطبق
"PREFERRED_DEALERSHIP" اختيار الوكيل المفضّل لك لا ينطبق
"VEHICLE_PURCHASE_TIMELINE" ما هو الوقت المخطط لشراء مركبة؟ لا ينطبق
VEHICLE_CONDITION ما هو نوع حالة المركبة الذي يهمك؟ لا ينطبق
"VEHICLE_OWNERSHIP" هل لديك مركبة؟ "غير متوفّر"
"VEHICLE_PAYMENT_TYPE" ما هو خيار ملكية المركبة الذي يهمك؟ لا ينطبق
"COMPANY_SIZE" ما هو حجم شركتك؟ لا ينطبق
"ANNUAL_SALES" ما هو حجم مبيعاتك السنوية؟ لا ينطبق
"YEARS_IN_BUSINESS" كم عدد السنوات التي قضيتها في ممارسة عملك؟ لا ينطبق
"JOB_DEPARTMENT" ما هي الإدارة الوظيفية؟ لا ينطبق
"JOB_ROLE" ما هو دورك الوظيفي؟ لا ينطبق
"EDUCATION_PROGRAM" ما هو البرنامج الذي يهمك؟ لا ينطبق
"EDUCATION_COURSE" ما هي الدورة التدريبية التي تهمك؟ لا ينطبق
"PRODUCT" ما هو المنتج الذي يهمك؟ لا ينطبق
"SERVICE" ما هي الخدمة التي تهمك؟ لا ينطبق
"OFFER" ما هو العرض الذي يهمك؟ لا ينطبق
"CATEGORY" ما هي الفئة التي تهمك؟ لا ينطبق
"PREFERRED_CONTACT_METHOD" اختيار وسيلة الاتصال المفضّلة لك لا ينطبق
"PREFERRED_LOCATION" اختيار موقعك الجغرافي المفضّل لا ينطبق
"PREFERRED_CONTACT_TIME" ما هو أنسب وقت للتواصل معك؟ لا ينطبق
"PURCHASE_TIMELINE" متى يمكنك إجراء عملية شراء؟ لا ينطبق
"YEARS_OF_EXPERIENCE" ما هو عدد سنوات خبرتك في العمل؟ لا ينطبق
"JOB_INDUSTRY" ما هو مجال عملك؟ لا ينطبق
"LEVEL_OF_EDUCATION" ما هو أعلى مستوى تعليمي وصلت إليه؟ لا ينطبق
"PROPERTY_TYPE" ما هو نوع العقار المطلوب؟ لا ينطبق
"REALTOR_HELP_GOAL" ما هي الطريقة المطلوب أن يساعدك بها الوسيط العقاري؟ لا ينطبق
"PROPERTY_COMMUNITY" ما المنتدى الذي تهتم به؟ لا ينطبق
"PRICE_RANGE" ما هو نطاق السعر المطلوب؟ لا ينطبق
"NUMBER_OF_BEDROOMS" كم عدد غرف النوم المطلوب؟ لا ينطبق
"FURNISHED_PROPERTY" هل المطلوب عقار مفروش بالكامل؟ لا ينطبق
"PETS_ALLOWED_PROPERTY" هل المطلوب عقارات يُسمَح فيها بالحيوانات الأليفة؟ لا ينطبق
"NEXT_PLANNED_PURCHASE" ما هو المنتج التالي الذي خططت لشرائه؟ لا ينطبق
"EVENT_SIGNUP_INTEREST" هل يهمك الاشتراك في أحد الأحداث؟ لا ينطبق
"PREFERRED_SHOPPING_PLACES" ما هي الأماكن التي يهمك التسوّق منها؟ لا ينطبق
FAVORITE_BRAND ما هي العلامة التجارية المفضّلة لديك؟ لا ينطبق
"TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" أي نوع من التراخيص التجارية الصالحة لديك؟ لا ينطبق
"EVENT_BOOKING_INTEREST" هل يهمّك حجز تذكرة لحضور فعالية ما؟ لا ينطبق
"DESTINATION_COUNTRY" ما هو بلد الوجهة؟ لا ينطبق
DESTINATION_CITY ما هي مدينة الوجهة؟ لا ينطبق
"DEPARTURE_COUNTRY" ما هو بلد المغادرة؟ لا ينطبق
"DEPARTURE_CITY" ما هي مدينة المغادرة؟ لا ينطبق
"DEPARTURE_DATE" ما هو تاريخ المغادرة؟ لا ينطبق
"RETURN_DATE" ما هو تاريخ العودة؟ لا ينطبق
"NUMBER_OF_TRAVELERS" كم عدد الأشخاص الذين سيرافقونك في السفر؟ لا ينطبق
"TRAVEL_BUDGET" ما هي ميزانية السفر؟ لا ينطبق
"TRAVEL_ACCOMMODATION" ما هو المكان المطلوب الإقامة فيه أثناء سفرك؟ لا ينطبق
asset_group_id لا تتم تعبئة هذا الحقل إلا في "حملات الأداء الأفضل". يشير ذلك إلى رقم تعريف الحاوية التي تتضمّن نموذج العملاء المحتملين.

يجب أن يستخدم العملاء عددًا صحيحًا من 8 بايت للمعالجة.

lead_stage تشير هذه السمة إلى مرحلة العميل المحتمل في وقت تسليم العميل المحتمل. يفيد هذا الحقل في تتبُّع مرحلة مسار الإحالة الناجحة / حالة الإحالة الناجحة لأحد العملاء المحتملين.
lead_submit_time تشير هذه السمة إلى الطابع الزمني الذي أرسل فيه المستخدِم النموذج. ويتم تمثيله بالتنسيق ISO-8601. مثال: 2024-09-26T12:30:00Z

الحقول غير المعروفة والتوافق مع الإصدارات المستقبلية

لضمان استمرار فعالية عملية دمج خطاف الويب وإمكانية تكيّفها مع التحسينات المستقبلية، من أفضل الممارسات الشائعة تصميم محلّل JSON لتجاهل أي حقول في حمولة خطاف الويب لا يستهلكها نظامك أو يتعرّف عليها بشكل صريح.

اقتراح أساسي: اضبط منطق تحليل JSON لمعالجة الحقول التي تحتاج إليها تحديدًا في تطبيقك فقط. لا تكتب رمزًا برمجيًا يتوقّع مجموعة ثابتة من الحقول أو قد يتعذّر تنفيذه إذا كانت هناك حقول جديدة غير متوقّعة في الحمولة.

سبب أهمية ذلك:

  • التوافق مع الإصدارات المستقبلية: قد تضيف Google حقولاً جديدة اختيارية إلى حمولة Webhook في التحديثات المستقبلية لتوفير بيانات أكثر تفصيلاً أو ميزات جديدة. إذا كان المحلّل اللغوي الخاص بك صارمًا جدًا (على سبيل المثال، يتعذّر عليه التعامل مع السمات غير المعروفة)، قد يتعطّل الدمج عند طرح 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"} نعم

مكرّرة

لا يمكن ضمان تسليم بيانات العميل المحتمل مرة واحدة بالضبط، وبالتالي يجب أن يتعامل الويب هوك الخاص بمعالجة بيانات العملاء المحتملين مع النسخ المكرّرة بشكلٍ سليم.