שליחת אירועים

אתם יכולים לעבור על המדריך למתחילים הזה כדי להכיר את שליחת נתוני אירועים.

משתמשים ב-Data Manager API באחד מהתרחישים הבאים:

  • כדי למקסם את האותות של האינטראקציות עם המודעות ולשפר את הנתונים והביצועים הכוללים, אתם יכולים לשלוח המרות של תג Google Ads או אירועים של purchase Google Analytics כמקור נתונים נוסף להמרות של התג.

    התכונה הזו זמינה בכל חשבונות Google Ads, אבל היא זמינה רק לנכסי Google Analytics שנכללים ברשימת ההיתרים. אם אתם רוצים להוסיף את נכס Google Analytics שלכם לרשימת ההיתרים, אתם יכולים למלא את הטופס הזה.

  • שליחת נתוני אירועים להמרות אופליין או להמרות משופרות לצורך שיוך ללידים ב-Google Ads.

בוחרים את הגרסה של המדריך שרוצים לראות:

במדריך למתחילים הזה תבצעו את הפעולות הבאות:

  1. מכינים Destination לקבלת נתוני אירועים.
  2. מכינים את נתוני האירועים לשליחה.
  3. יצירת בקשת IngestionService לאירועים.
  4. שולחים את הבקשה באמצעות Google APIs Explorer.
  5. הסבר על תגובות הצלחה ותגובות כישלון.

הכנת היעדים

לפני ששולחים נתונים, צריך להכין לפחות Destination אחד לנתונים. הנה דוגמה לDestination שאפשר להשתמש בה:

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

אלה השדות של Destination. במאמר הגדרת יעדים אפשר למצוא פרטים נוספים ודוגמאות ליעדים בתרחישים שונים.

operatingAccount

החשבון שמקבל את האירועים.

במקרה של אירועים שנשלחים כמקור נתונים נוסף, החשבון הפעיל יכול להיות חשבון Google Ads או נכס ב-Google Analytics.

אם הערך של accountType הוא GOOGLE_ANALYTICS_PROPERTY, פרטי הכניסה של הבקשה צריכים להיות של משתמש Google Analytics עם תפקיד עורך או אדמין בנכס.

כדי לייבא נתוני המרות אופליין (OCI) ולהפעיל המרות משופרות לצורך שיוך ללידים, החשבון הפעיל חייב להיות חשבון Google Ads.

loginAccount
החשבון שבו חשבון Google של פרטי הכניסה הוא משתמש.
productDestinationId

המזהה של הישות ב-operatingAccount שמקבלת את האירועים.

עבור אירועים שנשלחים כמקור נתונים נוסף, הערך של productDestinationId חייב להיות אחד מהערכים הבאים:

  1. המזהה של המרה ב-Google Ads עם הערך WEBPAGE של type. בממשק המשתמש של Google Ads, מקור ההמרה של פעולת המרה מסוג WEBPAGE הוא אתר.

  2. מזהה המדידה של מקור לנתוני אתר ב-Google Analytics. אי אפשר לשלוח אירועים כמקור נתונים נוסף למקור נתוני אפליקציה ל-iOS או ל-Android ב-Google Analytics.

במקרה של המרות אופליין או המרות משופרות לצורך שיוך ללידים, הערך של productDestinationId צריך להיות המזהה של פעולת המרה ב-Google Ads עם הערך UPLOAD_CLICKS של type. בממשק המשתמש של Google Ads, מקור ההמרה של פעולת המרה מסוג UPLOAD_CLICKS הוא אתר (ייבוא מקליקים).

בדוגמה שבמדריך הזה מוסבר איך ליצור בקשה ששולחת כל אירוע לאותו יעד. אם רוצים לשלוח אירועים לכמה יעדים באותה בקשה, אפשר לעיין במאמר בנושא שליחת אירועים לכמה יעדים.

הכנת נתוני אירועים

כדאי לעיין בנתוני האירועים הבאים. כל טבלה תואמת לאירוע המרה אחד. לכל אירוע המרה יש חותמת זמן של האירוע, פעולת ההמרה וערך ההמרה.

יכול להיות שבכל אירוע יהיו מזהי מודעות, כמו gclid, או מזהי משתמשים, כמו כתובות אימייל, מספרי טלפון ופרטי כתובת. אירוע יכול לכלול גם:

  • מידע על המשתמש שנבדק בזמן האירוע, כמו ערך הלקוח או אם הוא לקוח חדש, חוזר או שהיה לא פעיל וחזר לפעילות.
  • נתוני עגלות קניות.
  • פרמטרים נוספים של אירועים או מאפייני משתמש ליעד, כמו ‫client_id או user_id ל-Google Analytics.

אלה נתוני האירוע:

אירוע 1

אירוע מס' 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 30.03
currency USD
gclid GCLID_1
emails
given_name John
family_name Smith-Jones
region_code us
postal_code 94045
customer_type NEW
customer_value_bucket HIGH
client_id 1234567890.1761581763
user_id user_ABC12345
ad_unit_name Banner_01
event_name purchase
פריטים בעגלת הקניות
item_id SKU_12345
item_name Stan and Friends Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 2.22
item_index 0
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 10.01
item_quantity 3

אירוע 2

אירוע מס' 2
conversion_time June 10, 2025 11:42:33PM America/New_York
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 42.02
currency eur
gclid GCLID_2
emails

zoe@EXAMPLE.COM

cloudy.sanfrancisco@gmail.com
given_name zoë
family_name pérez
region_code PT
postal_code 1229-076
customer_type RETURNING
client_id 9876543210.1761582117
user_id user_DEF9876
ad_unit_name Banner_02
event_name purchase
פריטים בעגלת הקניות
item_id SKU_12346
item_name Google Grey Women's Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 3.33
item_index 1
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 21.01
item_quantity 2

עיצוב הנתונים

הפורמט של השדות צריך להיות כמו שמופיע במדריך הפורמט. אלה נתוני האירוע אחרי העיצוב:

אירוע 1

אירוע מס' 1
conversion_time 2025-06-10T15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 30.03
currency USD
gclid GCLID_1
emails
given_name john
family_name smith-jones
region_code US
postal_code 94045
customer_type NEW
customer_value_bucket HIGH
client_id 1234567890.1761581763
user_id user_ABC12345
ad_unit_name Banner_01
event_name purchase
פריטים בעגלת הקניות
item_id SKU_12345
item_name Stan and Friends Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 2.22
item_index 0
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 10.01
item_quantity 3

אירוע 2

אירוע מס' 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 42.02
currency EUR
gclid GCLID_2
emails

zoe@example.com

cloudysanfrancisco@gmail.com
given_name zoë
family_name pérez
region_code PT
postal_code 1229-076
customer_type RETURNING
client_id 9876543210.1761582117
user_id user_DEF9876
ad_unit_name Banner_02
event_name purchase
פריטים בעגלת הקניות
item_id SKU_12346
item_name Google Grey Women's Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 3.33
item_index 1
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 21.01
item_quantity 2

גיבוב וקידוד הנתונים

בנוסף, צריך לבצע גיבוב של כתובות האימייל, השמות הפרטיים ושמות המשפחה בפורמט באמצעות אלגוריתם SHA-256 וקידוד באמצעות קידוד הקסדצימלי או Base64. אלה נתוני האירוע אחרי קביעת הפורמט, הגיבוב והקידוד באמצעות קידוד הקסדצימלי:

אירוע 1

אירוע מס' 1
conversion_time 2025-06-10T15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 30.03
currency USD
gclid GCLID_1
emails
given_name 96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A
family_name DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081
region_code US
postal_code 94045
customer_type NEW
customer_value_bucket HIGH
client_id 1234567890.1761581763
user_id user_ABC12345
ad_unit_name Banner_01
event_name purchase
פריטים בעגלת הקניות
item_id SKU_12345
item_name Stan and Friends Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 2.22
item_index 0
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 10.01
item_quantity 3

אירוע 2

אירוע מס' 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 42.02
currency EUR
gclid GCLID_2
emails

3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250

223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4
given_name 2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450
family_name 6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F
region_code PT
postal_code 1229-076
customer_type RETURNING
client_id 9876543210.1761582117
user_id user_DEF9876
ad_unit_name Banner_02
event_name purchase
פריטים בעגלת הקניות
item_id SKU_12346
item_name Google Grey Women's Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 3.33
item_index 1
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 21.01
item_quantity 2

המרת הנתונים לאובייקטים של Event

ממירים את הנתונים המגובבים והמפורמטים של כל אירוע ל-Event. ממלאים את השדות הבאים לפי ההנחיות:

  1. מגדירים את eventTimestamp לשעה שבה האירוע התרחש.

    האירועים ב-Google Analytics צריכים לכלול חותמת זמן eventTimestamp מ-72 השעות האחרונות.

  2. מגדירים את שדות החובה לתרחיש לדוגמה.

    תרחיש שימוש מזהים transactionId eventSource
    המרות אופליין או המרות משופרות לצורך שיוך ללידים נדרש. מגדירים לפחות אחד מהערכים הבאים: אופציונלי נדרש. מגדירים אחד מערכי ה-enum של EventSource.
    אירועים שנשלחים כמקור נתונים נוסף ליעד ב-Google Ads נדרש. מגדירים לפחות אחד מהערכים הבאים:
    • ‫adIdentifiers עם הגדרה של לפחות אחד מהערכים gclid, gbraid או wbraid
    • userData
    		 חובה אופציונלי. אם הוא מוגדר, הערך שלו חייב להיות WEB.
    אירועים שנשלחים כמקור נתונים נוסף ליעד ב-Google Analytics נדרש. מגדירים לפחות אחד מהערכים הבאים: חובה אופציונלי. אם הוא מוגדר, הערך שלו חייב להיות WEB.

  3. אם אתם שולחים אירועים כמקור נתונים נוסף ליעד ב-Google Ads, כדאי לעיין במאמר איך Google מטפלת בנתונים ממקורות נתונים נוספים.

  4. ממלאים את שאר השדות שרוצים להוסיף להם ערך. רשימה מלאה של השדות הזמינים מופיעה במסמכי העזר בנושא Event.

איך Google מטפלת בנתונים ממקורות נתונים נוספים

במסגרת אותה פעולת המרה, Google משתמשת ב-transactionId כדי לבטל כפילויות של אירועי המרה שנשלחים ממקורות שונים (כמו תג האתר ובקשות להעברה של נתונים באמצעות Data Manager API). בטבלה הבאה מוסבר איך המערכת מעבדת את הנתונים מהבקשות להעברה.

תרחיש שדה נתונים איך המידע מעובד
transactionId זהה לערך של אירוע קיים של תג ‫conversionValue (עם currencyCode)

העדכון הושלם. הערך conversionValue (עם currencyCode) מהתג Event מבטל את הערך המקורי שתועד על ידי התג.

הערה: במהלך תקופת הניסיון הראשונית של 14 יום לפעולת המרה, האפשרות 'עדכוני ערכים' מושבתת. הערך של התג לא יוחלף בדוחות של Google Ads עד שתקופת הניסיון תסתיים.

transactionId זהה לערך של אירוע קיים של תג שדות אחרים חוץ מ-conversionValue או currencyCode (למשל, adIdentifiers.gclid) המערכת מתעלמת מהערך. ערכים אחרים בשדות ממקור הנתונים הנוסף לא יחליפו את הערכים בשדות שתועדו במקור על ידי Google Tag לגבי עסקאות תואמות.
הערך של transactionId לא תואם לאף אירוע קיים כל הנתונים שסופקו (לדוגמה, userData, conversionValue, currencyCode)

המערכת משתמשת בזה ליצירת אירוע המרה חדש. לאחר מכן, Google תנסה לשייך את ההמרה החדשה הזו לקליק על מודעה באמצעות המזהים שסיפקתם (כמו adIdentifiers.gclid או userData).

הערה: במהלך תקופת הניסיון הראשונית של 14 יום, ההמרות החדשות שנוצרו יופיעו בדוחות אבל לא ישמשו לבידינג. אחרי שתקופת הניסיון תסתיים, הן ייפתחו לבידינג באופן אוטומטי.

הוספת מאפייני סשן

אם אתם שולחים המרות אופליין או המרות משופרות לצורך שיוך ללידים, כדאי להוסיף מאפייני סשן כשמזהים אחרים של מודעות, כמו GCLID או WBRAID, לא זמינים. אפשר לכלול גם מאפייני סשן בנוסף למזהי מודעות אחרים.

מאפייני הסשן מספקים הקשר ואותות נוספים על האינטראקציה של המשתמשים עם האתר שלכם. האלמנטים האלה יכולים לשפר את הדיוק של מעקב ההמרות, הדיווח והבידינג.

ב-Data Manager API, יש שתי גישות שבהן אפשר להשתמש כדי לשלוח מאפייני סשן:

  1. מומלץ: מגדירים את השדה sessionAttributes של adIdentifiers למחרוזת של מאפייני הסשן בקידוד Base64. כדי לשלוף את המחרוזת המוצפנת, פועלים לפי ההוראות במאמר בנושא שליפת מידע מ-session_attributes כדי לשנות את הדפים שבהם מגישים טופס באתר.

  2. אם אתם לא יכולים להשתמש ב-JavaScript, אתם יכולים לשלוף את השדות של מאפייני הסשן הנפרדים ולהוסיף כל אחד מהם לרשימה experimentalFields כExperimentalField נפרד:

    • gad_campaignid
    • session_start_time_usec
    • gad_source
    • landing_page_url
    • landing_page_referrer

    אם יש לכם ערך למאפיין הסשן landing_page_user_agent, אתם צריכים לשלוח אותו בשדה userAgent של adIdentifiers.landingPageDeviceInfo.

    ריכזנו כאן שיטות מומלצות לשליחת צמדי מפתח/ערך נפרדים:

    • שליחה עקבית של gad_campaignid ושל session_start_time_usec. השדות האלה חיוניים לשיוך מדויק.
    • אל תציינו ערך landing_page_url לא מדויק או חלקי, כמו מחרוזת placeholder, נתיב של אפליקציה פנימית או כתובת URL לא מלאה. אם אין לכם את כתובת ה-URL המדויקת והמלאה, אל תציינו את landing_page_url.

    זו דוגמה לחלק מאירוע עם רשומות ב-experimentalFields עבור gad_campaignid ו-session_start_time_usec, וסוכן המשתמש בשדה landingPageDeviceInfo:

    {
  ...,
  "experimentalFields": [
    {
      "field": "gad_campaignid",
      "value": "21288051566"
    },
    {
      "field": "session_start_time_usec",
      "value": "1767711548052000"
    }
  ],
  "adIdentifiers": {
    "landingPageDeviceInfo": {
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
    }
  }
}

הוספת מידע מ-Google Analytics

אם היעדים של אירוע שנשלח כמקור נתונים נוסף כוללים נכס Google Analytics, צריך למלא את השדות הבאים כמו שמצוין:

eventName

נדרש. השם של האירוע ב-Google Analytics.

transactionId

חובה . המזהה הייחודי של האירוע.

מזהה אחד לפחות

צריך להגדיר לפחות אחד מהשדות הבאים:

destinationReferences

חובה אם רשימת destinations ברמת הבקשה מכילה יותר מ-Google Analytics Destination אחד. מוסיפים רשומה ל-destinationReferences כדי לציין לאיזה יעד ב-Google Analytics צריך לשלוח את האירוע. מידע נוסף על הפניות ליעדים זמין במאמר בנושא שליחת אירועים למספר יעדים.

אם הפרמטר destinationReferences לא מוגדר או שיש לו כמה ערכים שמפנים ליעדים ב-Google Analytics, ה-API של המרכז לניהול נתונים דוחה את האירוע עם השגיאה MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT.

userId

אופציונלי. User-ID של המשתמש.

additionalEventParameters

אופציונלי, אבל מומלץ. מאכלסים את הרשימה הזו בכל הפרמטרים של אירועים ב-Google Analytics שלא נכללים בשדות האחרים Event. הפרמטרים יכולים לכלול פרמטרים מומלצים נוספים מpurchaseהאירוע, או פרמטרים אחרים שרוצים לתעד. משתמשים בשם הפרמטר של Google Analytics עבור parameterName של EventParameter.

לדוגמה, אם יש לכם את המיסים שמשויכים לעסקה, מוסיפים רשומה ל-additionalEventParameters עם הערך tax במאפיין parameterName, ועם עלות המס במאפיין value.

אנחנו לא ממליצים להוסיף רשומות לפרמטרים של אירועים ב-Google Analytics‏: transactionId, currency או value. במקום זאת, מאכלסים את הערכים transactionId, currency ו-conversionValue של Event, שמקבלים עדיפות על פני כל הערכים ב-additionalEventParameters.

הוספת נתוני עגלות קניות לאירועי רכישה

מאכלסים את השדה cartData של Event במידע על הפריטים שנרכשו. לכל פריט שנרכש, מוסיפים אובייקט Item לרשימה items של CartData ומאכלסים את השדות הבאים כמו שמופיע:

itemId
חובה. מזהה ייחודי של הפריט.
unitPrice

נדרש. המחיר ליחידה לא כולל מס, משלוח והנחות ברמת האירוע (ברמת העסקה).

אם הפריט נמכר בהנחה ברמת הפריט, צריך להשתמש במחיר היחידה המוזל. לדוגמה, אם המחיר ליחידה של פריט הוא 27.67 וההנחה ליחידה היא 6.66, צריך להגדיר את unitPrice ל-21.01.

quantity

נדרש. כמות היחידות שנרכשו מהפריט הספציפי הזה.

additionalItemParameters

מאכלסים את הרשימה הזו בכל הפרמטרים ברמת הפריט שלא נכללים בשדות האחרים של Item. משתמשים בשם פרמטר הפריט של Google Analytics עבור parameterName של ItemParameter.

לדוגמה, אם יש לכם מותג וקטגוריה של פריט, מוסיפים רשומה לadditionalItemParameters של הפריט עם parameterName שמוגדר כ-item_brand וvalue שמוגדר כשם המותג, ורשומה נוספת עם parameterName שמוגדר כ-item_category וvalue שמוגדר כקטגוריה של הפריט.

אנחנו לא ממליצים להוסיף רשומות לפרמטרים של פריטים ב-Google Analytics‏ quantity, price או item_id. במקום זאת, צריך למלא את הערכים itemId, unitPrice ו-quantity של Item, שמקבלים עדיפות על פני כל הערכים ב-additionalItemParameters.

הנה דוגמה ל-Event של הנתונים המעוצבים, המגובבים והמקודדים מהאירוע השני, עם נתונים נוספים ל-Google Analytics:

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

יצירת גוף הבקשה

כדי ליצור את גוף הבקשה, משלבים את destinations ו-events, מגדירים את השדה encoding ומוסיפים שדות בקשה אחרים שרוצים לכלול, כמו validateOnly ו-consent.

הדוגמאות במדריך הזה לא משתמשות בהצפנה, אבל אפשר לפעול לפי ההוראות במאמר הצפנת נתוני משתמשים כדי להוסיף הצפנה לתהליך.

שליחת הבקשה

  1. לוחצים על Open in API Explorer כדי לפתוח את API Explorer בכרטיסייה או בחלון חדשים.
  2. בגוף הבקשה בכלי API Explorer, מחליפים כל מחרוזת שמתחילה ב-REPLACE_WITH, כמו REPLACE_WITH_OPERATING_ACCOUNT_TYPE, בערך הרלוונטי.
  3. לוחצים על Execute (ביצוע) בחלק התחתון של הדף API Explorer ומשלימים את הנחיות ההרשאה כדי לשלוח את הבקשה.
  4. מגדירים את validateOnly ל-true כדי לאמת את הבקשה בלי להחיל את השינויים. כשמוכנים להחיל את השינויים, מגדירים את validateOnly לערך false.

בקשה להטמעת נתונים

פתיחה ב-API Explorer 
{
    "destinations": [
        {
            "operatingAccount": {
                "accountType": "OPERATING_ACCOUNT_TYPE",
                "accountId": "OPERATING_ACCOUNT_ID"
            },
            "loginAccount": {
                "accountType": "LOGIN_ACCOUNT_TYPE",
                "accountId": "LOGIN_ACCOUNT_ID"
            },
            "productDestinationId": "CONVERSION_ACTION_ID"
        }
    ],
    "encoding": "HEX",
    "events": [
        {
            "adIdentifiers": {
                "gclid": "GCLID_1"
            },
            "conversionValue": 30.03,
            "currency": "USD",
            "eventTimestamp": "2025-06-10T20:07:01Z",
            "transactionId": "ABC798654321",
            "eventSource": "WEB",
            "userData": {
                "userIdentifiers": [
                    {
                        "address": {
                            "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
                            "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
                            "regionCode": "US",
                            "postalCode": "94045"
                        }
                    }
                ]
            },
            "userProperties": {
                "customerType": "NEW",
                "customerValueBucket": "HIGH"
            },
            "eventName": "purchase",
            "clientId": "1234567890.1761581763",
            "userId": "user_ABC12345",
            "additionalEventParameters": [
                {
                    "parameterName": "ad_unit_name",
                    "value": "Banner_01"
                }
            ],
            "cartData": {
                "transactionDiscount": 6.66,
                "items": [
                    {
                        "itemId": "SKU_12345",
                        "quantity": 3,
                        "unitPrice": 10.01,
                        "additionalItemParameters": [
                            {
                                "parameterName": "item_name",
                                "value": "Stan and Friends Tee"
                            },
                            {
                                "parameterName": "affiliation",
                                "value": "Google Merchandise Store"
                            },
                            {
                                "parameterName": "coupon",
                                "value": "SUMMER_FUN"
                            },
                            {
                                "parameterName": "discount",
                                "value": "2.22"
                            },
                            {
                                "parameterName": "index",
                                "value": "0"
                            },
                            {
                                "parameterName": "item_brand",
                                "value": "Google"
                            },
                            {
                                "parameterName": "item_category",
                                "value": "Apparel"
                            },
                            {
                                "parameterName": "item_category2",
                                "value": "Adult"
                            },
                            {
                                "parameterName": "item_category3",
                                "value": "Shirts"
                            },
                            {
                                "parameterName": "item_category4",
                                "value": "Crew"
                            },
                            {
                                "parameterName": "item_category5",
                                "value": "Short sleeve"
                            },
                            {
                                "parameterName": "item_list_id",
                                "value": "related_products"
                            },
                            {
                                "parameterName": "item_list_name",
                                "value": "Related Products"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "adIdentifiers": {
                "gclid": "GCLID_2"
            },
            "conversionValue": 42.02,
            "currency": "EUR",
            "eventTimestamp": "2025-06-11T04:42:33Z",
            "transactionId": "DEF999911111",
            "eventSource": "WEB",
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
                    },
                    {
                        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
                    },
                    {
                        "address": {
                            "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
                            "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
                            "regionCode": "PT",
                            "postalCode": "1229-076"
                        }
                    }
                ]
            },
            "userProperties": {
                "customerType": "RETURNING"
            },
            "eventName": "purchase",
            "clientId": "9876543210.1761582117",
            "userId": "user_DEF9876",
            "additionalEventParameters": [
                {
                    "parameterName": "ad_unit_name",
                    "value": "Banner_02"
                }
            ],
            "cartData": {
                "transactionDiscount": 6.66,
                "items": [
                    {
                        "itemId": "SKU_12346",
                        "quantity": 2,
                        "unitPrice": 21.01,
                        "additionalItemParameters": [
                            {
                                "parameterName": "item_name",
                                "value": "Google Grey Women's Tee"
                            },
                            {
                                "parameterName": "affiliation",
                                "value": "Google Merchandise Store"
                            },
                            {
                                "parameterName": "coupon",
                                "value": "SUMMER_FUN"
                            },
                            {
                                "parameterName": "discount",
                                "value": "3.33"
                            },
                            {
                                "parameterName": "index",
                                "value": "1"
                            },
                            {
                                "parameterName": "item_brand",
                                "value": "Google"
                            },
                            {
                                "parameterName": "item_category",
                                "value": "Apparel"
                            },
                            {
                                "parameterName": "item_category2",
                                "value": "Adult"
                            },
                            {
                                "parameterName": "item_category3",
                                "value": "Shirts"
                            },
                            {
                                "parameterName": "item_category4",
                                "value": "Crew"
                            },
                            {
                                "parameterName": "item_category5",
                                "value": "Short sleeve"
                            },
                            {
                                "parameterName": "item_list_id",
                                "value": "related_products"
                            },
                            {
                                "parameterName": "item_list_name",
                                "value": "Related Products"
                            }
                        ]
                    }
                ]
            }
        }
    ],
    "validateOnly": true
}

תגובות שבוצעו בהצלחה

בקשה שמושלמת בהצלחה מחזירה תגובה עם אובייקט שמכיל requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

כדאי לתעד את requestId שמוחזר כדי שתוכלו לאחזר אבחון כשכל יעד בבקשה יעבור עיבוד.

תגובות שגיאה

בקשה שנכשלה מניבה קוד סטטוס של תגובה עם שגיאה, כמו 400 Bad Request, ותגובה עם פרטי השגיאה.

לדוגמה, אם emailAddress מכיל מחרוזת של טקסט פשוט במקום ערך בקידוד הקסדצימלי, התגובה הבאה תתקבל:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

אם מחזירים את הערך emailAddress ללא גיבוב, אלא רק עם קידוד הקסדצימלי, התשובה תהיה:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

שליחת אירועים למספר יעדים

אם הנתונים שלכם מכילים אירועים ליעדים שונים, אתם יכולים לשלוח אותם באותה בקשה באמצעות הפניות ליעדים.

לדוגמה, אם יש לכם אירוע עם מזהה פעולת ההמרה 123456789 ואירוע נוסף עם מזהה פעולת ההמרה 777111122, אתם יכולים לשלוח את שני האירועים בבקשה אחת על ידי הגדרת reference של כל Destination. הערך של reference מוגדר על ידי המשתמש. הדרישה היחידה היא שלכל Destination יהיה reference ייחודי. זו רשימת destinations ששונתה עבור הבקשה:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

מגדירים את destinationReferences של כל Event כדי לשלוח אותו ליעד ספציפי אחד או יותר. לדוגמה, הנה Event שרלוונטי רק ל-Destination הראשון, ולכן רשימת ה-destinationReferences שלו מכילה רק את reference של Destination הראשון:

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

השדה destinationReferences הוא רשימה, כך שאפשר לציין כמה יעדים לאירוע. אם לא מגדירים את destinationReferences של Event, ה-API של המרכז לניהול נתונים שולח את האירוע לכל היעדים בבקשה.

אם לאירוע יש כמה יעדים, ה-API של המרכז לניהול נתונים שולח שדות רלוונטיים לכל יעד. לדוגמה, אם לאירוע יש יעד ב-Google Ads ויעד ב-Google Analytics, ה-API כולל שדות של Google Analytics כמו clientId או eventName כששולחים את האירוע ליעד ב-Google Analytics, וכולל שדות של Google Ads כמו customVariables כששולחים את האירוע ליעד ב-Google Ads.

השלבים הבאים

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