التنفيذ

مخطّط POST

سيكون طلب POST المُرسَل إلى رابط الويب للإجراءات بتنسيق 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_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" اسم العائلة للمستخدِم. "اسم العائلة"
"EMAIL" عنوان البريد الإلكتروني للمستخدِم. "البريد الإلكتروني للمستخدم"
"PHONE_NUMBER" رقم هاتف المستخدم بتنسيق E.164، على سبيل المثال: "+11234567890" "هاتف المستخدم"
"POSTAL_CODE" الرمز البريدي للمستخدِم. "الرمز البريدي"
"COMPANY_NAME" اسم شركة المستخدم. "اسم الشركة"
"JOB_TITLE" المسمى الوظيفي للمستخدم "عنوان الوظيفة"
"WORK_EMAIL" عنوان البريد الإلكتروني للعمل الخاص بالمستخدم "البريد الإلكتروني للعمل"
"WORK_PHONE" رقم هاتف العمل للمستخدم. "هاتف العمل"
"STREET_ADDRESS" عنوان الشارع للمستخدِم "عنوان الشارع"
"CITY" مدينة المستخدم. "المدينة"
"REGION" منطقة المستخدم "المنطقة"
"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 بايت لمعالجته.

معالجة العملاء المحتملِين

يجب أن تستجيب معالجات العملاء المحتملين برموز HTTP التالية:

استجابة HTTP نص الاستجابة (بتنسيق JSON) هل الخطأ قابل للاسترجاع؟
200 {} لا ينطبق
4XX {"message: Free form error text, describing what was wrong with request"} لا
5XX {"message: Intermittent retraible error optional message"} نعم

جهات الاتصال المكررة

لا يمكن ضمان تسليم عميل محتمل واحد مرّة واحدة بالضبط، لذا يجب أن يتعامل الردّ التلقائي على الويب المخصّص لمعالجة العملاء المحتملين مع النُسخ المكرّرة بسلاسة.