יישום

סכימת POST

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

מטען ייעודי (payload) של פרוטוקול Webhook

// 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. במוצר הנוכחי אפשר לצרף טופס ברמת הקמפיין (לעומת צירוף ברמת קבוצת המודעות או המודעה).

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

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

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

הלקוחות צריכים להשתמש במספר שלם באורך 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" השם המלא של המשתמש. ‫"Full Name" (שם מלא)
"FIRST_NAME" השם הפרטי של המשתמש. ‫"First Name" (שם פרטי)
"LAST_NAME" שם המשפחה של המשתמש. 'שם משפחה'
"EMAIL" כתובת האימייל של המשתמש. ‫"User Email" ‏(אימייל של המשתמש)
"PHONE_NUMBER" מספר הטלפון של המשתמש בפורמט E.164, לדוגמה: "+11234567890". ‫"User Phone" (טלפון המשתמש)
"PHONE_NUMBER_VERIFIED" האם מספר הטלפון של המשתמש אומת. 'מספר הטלפון אומת'
"POSTAL_CODE" המיקוד של המשתמש. ‫"Postal Code" (מיקוד)
"COMPANY_NAME" שם החברה של המשתמש. ‫"Company Name" (שם החברה)
"JOB_TITLE" שם התפקיד של המשתמש. ‫"Job Title" (שם המשרה)
‪"WORK_EMAIL" כתובת האימייל של המשתמש בעבודה. 'אימייל לעבודה'
"WORK_PHONE" מספר הטלפון של המשתמש בעבודה. "Work Phone" (טלפון בעבודה)
"STREET_ADDRESS" הרחוב ומספר הבית של המשתמש. ‫"Street Address" (כתובת)
"CITY" העיר של המשתמש. ‫"City" ‏(עיר)
‫"REGION" האזור של המשתמש. ‫"Region" ‏(אזור)
"COUNTRY" המדינה של המשתמש. ‫"Country" ‏(מדינה)
‫"VEHICLE_MODEL" איזה דגם מעניין אותך? לא רלוונטי
"VEHICLE_TYPE" איזה סוג של רכב מעניין אותך? לא רלוונטי
"PREFERRED_DEALERSHIP" יש לבחור את סוכנות הרכב המועדפת לא רלוונטי
"VEHICLE_PURCHASE_TIMELINE" מתי תכננת לקנות רכב? לא רלוונטי
"VEHICLE_CONDITION" באיזה מצב צריך להיות הרכב? לא רלוונטי
‫"VEHICLE_OWNERSHIP" יש לך רכב? ‫"N/A"
‫"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

שדות לא מוכרים ותאימות קדימה

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

המלצה חשובה: כדאי להגדיר את הלוגיקה של ניתוח ה-JSON כך שתעבד רק את השדות שנדרשים באופן ספציפי לאפליקציה. אל תכתבו קוד שמצפה לקבוצה קבועה של שדות או שייכשל אם יש מטען ייעודי (payload) עם שדות חדשים ולא צפויים.

למה זה חשוב:

  • תאימות קדימה: יכול להיות ש-Google תוסיף שדות אופציונליים חדשים למטען הייעודי (payload) של ה-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"} כן

כפילויות

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