יישום

סכימת 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 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];
  // The source of the lead submission.
  // Possible values: "LEAD_FORM" or "CONVERSATIONAL_AGENT".
  string lead_source = 14 [(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" השם הפרטי של המשתמש. 'שם פרטי'
"LAST_NAME" שם המשפחה של המשתמש. 'שם משפחה'
"EMAIL" כתובת האימייל של המשתמש. ‫"User Email" (כתובת האימייל של המשתמש)
"PHONE_NUMBER" מספר הטלפון של המשתמש בפורמט E.164, לדוגמה, "+11234567890". "טלפון המשתמש"
"PHONE_NUMBER_VERIFIED" האם מספר הטלפון של המשתמש אומת. 'מספר הטלפון אומת'
"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
lead_source המאפיין הזה מציין את המקור של שליחת הלידים. הערך יכול להיות LEAD_FORM עבור לידים שנוצרו ממודעת טופס להשארת פרטים רגילה, או CONVERSATIONAL_AGENT עבור לידים שנוצרו מחוויית צ'אט סוכני בחיפוש.

שדות לא מזוהים ותאימות קדימה

כדי לוודא שהאינטגרציה של ה-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 לטיפול בלידים צריכה לטפל בכפילויות בצורה חלקה.