הטמעה

הסכימה של POST

בקשת ה-POST שנשלחת ל-webhook תהיה בפורמט JSON עם הסכימה הבאה:

Payload של 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 גרסת ה-API שאליה שייכת הסכימה של הלידים. הוא ישמש במהלך המעבר לסכימה חדשה, וניתן להתעלם ממנו בינתיים.
form_id מזהה ייחודי לכל טופס שמוגדר ב-Google Ads. המוצר הנוכחי מאפשר לצרף טופס ברמת הקמפיין (לעומת צירוף ברמת קבוצת המודעות או ברמת המודעה).

השלכות: אפשר לפלח לידים רק ברמה form_id (כלומר ברמת הקמפיין).

לקוחות צריכים להשתמש במספר שלם באורך 8 בייטים לעיבוד.

campaign_id מזהה הקמפיין או מזהה הפריט (Display & Video 360) ב-Google Ads של טופס יצירת הלידים המצורף.

לקוחות צריכים להשתמש במספר שלם באורך 8 בייטים לעיבוד.

adgroup_id מזהה קבוצת המודעות ב-Google Ads משמש להבדיל בין קבוצת המודעות הספציפית בקמפיין. (האפשרות הזו זמינה רק ללידים ממודעות וידאו ומודעות Discovery)

לקוחות צריכים להשתמש במספר שלם באורך 8 בייטים לעיבוד.

creative_id מזהה הקריאייטיב ב-Google Ads משמש להבדיל בין הקריאייטיב הספציפי בקבוצת המודעות. (האפשרות הזו זמינה רק ללידים ממודעות וידאו ומודעות Discovery)

לקוחות צריכים להשתמש במספר שלם באורך 8 בייטים לעיבוד.

gcl_id מספר הקליק ב-Google, פרמטר ייחודי שמשמש למעקב אחרי כל קליק על מודעה.
google_key מפתח שהמפרסם מגדיר בכל טופס.

המלצה לטיפול: לפני עיבוד ליד שנשלח דרך ה-webhook, אימות השדה google_key זהה להגדרה ב-Google Ads, כדי להבטיח שהליד תקין. חשוב לשמור על הסודיות של המפתח הזה ולעדכן אותו ב-Google Ads אם יש סיבה להאמין שהוא דלף באופן נרחב.

is_test לשדה הזה יש סמנטיקה 'אופציונלית'. אם הערך הוא true, המערכת תתייחס ללידים האלה כלידים לבדיקה. אם הערך הוא false או שהשדה לא קיים, צריך להתייחס ללידים האלה כלידים תקינים בסביבת הייצור.
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"} כן

כפילויות

אין ערובה לכך שליד יחיד יישלח בדיוק פעם אחת, ולכן התגובה לפעולה מאתר אחר (webhook) לטיפול בלידים צריכה לטפל כראוי בעותקים כפולים.