דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

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

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

הכנת היעדים

לפני ששולחים נתונים, צריך להכין לפחות 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_ADS או GOOGLE_ANALYTICS_PROPERTY, ומגדירים את accountId לערך מספר הלקוח ב-Google Ads או מזהה הנכס ב-Google Analytics. אם הערך של accountType הוא GOOGLE_ANALYTICS_PROPERTY, פרטי הכניסה של הבקשה צריכים להיות של משתמש Google Analytics עם תפקיד עורך או אדמין בנכס.

במקרה של המרות אופליין והמרות משופרות לצורך שיוך ללידים, חשבון התפעול חייב להיות חשבון Google Ads, ולכן צריך להגדיר את accountType לערך GOOGLE_ADS ואת accountId למספר הלקוח ב-Google Ads.

loginAccount

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

אם פרטי הכניסה ל-OAuth הם של משתמש עם גישה לחשבון ניהול ב-Google Ads שכולל את operatingAccount כאחד מחשבונות המשנה שלו, נדרש loginAccount. מגדירים את accountId של loginAccount למזהה של חשבון הניהול, ואת accountType של loginAccount לערך GOOGLE_ADS.

אם פרטי הכניסה שלכם ל-OAuth הם של משתמש עם גישה ישירה ל-operatingAccount, אתם לא צריכים להגדיר את loginAccount, והערך שיוגדר כברירת מחדל יהיה operatingAccount. עם זאת, מומלץ להגדיר את loginAccount לאותם accountId וaccountType כמו operatingAccount. ההגדרה הזו עוזרת למנוע בעיות אם קבוצת החשבונות שהמשתמש יכול לגשת אליהם משתנה.

productDestinationId

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

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

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

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

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

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

יכול להיות שבכל אירוע יהיו מזהי מודעות, כמו 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. ממלאים את השדות הבאים כמו שמופיע כאן:

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

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

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

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

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

הערה: מערכות Google Ads ו-Google Analytics לא תומכות בהתאמה של כתובות IP למשתמשי קצה באזור הכלכלי האירופי (EEA), בבריטניה (UK) או בשווייץ (CH). צריך להוסיף לוגיקה כדי להחריג באופן מותנה את שיתוף כתובות ה-IP של משתמשים מהאזורים האלה, ולוודא שאתם מספקים למשתמשים מידע ברור ומקיף על הנתונים שאתם אוספים באתרים, באפליקציות ובנכסים אחרים שלכם, ומקבלים מהם הסכמה כנדרש על פי חוק או על פי מדיניות Google הרלוונטית. פרטים נוספים זמינים בדף מידע על ייבוא של נתוני המרות אופליין (OCI).

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

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

eventName

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

transactionId

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

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

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

‫clientId: מזהה ייחודי של מופע משתמש של לקוח אינטרנט. אפשר לעיין במאמר בנושא שליחת אירוע ל-Measurement Protocol.
‫adIdentifiers.gclid: מזהה קליק ב-Google.
‫userData: מזהים של המשתמש, כמו כתובות אימייל, מספרי טלפון או פרטי כתובת.

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 עם parameterName שמוגדר כ-tax ועם 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"
          }
        ]
      }
    ]
  }
}

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

משלבים את Destination ו-Events בגוף הבקשה:

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

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

      "productDestinationId": "CONVERSION_ACTION_1_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
}

מעדכנים את ה-placeholders בגוף ההודעה, כמו OPERATING_ACCOUNT_ID ו-PRODUCT_DESTINATION_ID, עם הערכים של החשבון והיעד.
מגדירים את validateOnly ל-true כדי לאמת את הבקשה בלי להחיל את השינויים. כשמוכנים להחיל את השינויים, מגדירים את validateOnly לערך false.
שימו לב שבמקרה הזה לא נעשה שימוש בהצפנה.

שליחת הבקשה

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

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

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

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

השלבים הבאים

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

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

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

הכנת היעדים

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

אירוע 1

אירוע 2

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

אירוע 1

אירוע 2

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

אירוע 1

אירוע 2

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

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

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

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

שליחת הבקשה

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

תגובות שמעידות על כשל

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

השלבים הבאים

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

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