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

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

אפשר להשתמש ב-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_ANALYTICS_PROPERTY, פרטי הכניסה של הבקשה צריכים להיות של משתמש Google Analytics עם תפקיד עורך או אדמין בנכס.

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

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

productDestinationId

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

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

המזהה של המרה ב-Google Ads עם הערך WEBPAGE בהגדרה type. בממשק המשתמש של Google Ads, מקור ההמרה של פעולת המרה מסוג WEBPAGE הוא אתר.
מזהה המדידה של מקור לנתוני אתר ב-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. ממלאים את השדות הבאים כמו שמופיע כאן:

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

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

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

תרחיש שימוש	מזהים	`transactionId`	`eventSource`
המרות אופליין או המרות משופרות לצורך שיוך ללידים	נדרש. מגדירים לפחות אחד מהערכים הבאים: `adIdentifiers` עם לפחות אחת מההגדרות `gclid`, `gbraid` או `wbraid` מאפייני סשן `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).

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

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

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

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

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

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

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

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

‫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 עם הערך 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"
          }
        ]
      }
    ]
  }
}

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

משלבים את 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 שלא עוברת גיבוב (hash) אלא רק קידוד הקסדצימלי, מפיקה את התגובה הבאה:

{
  "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, Data Manager API שולח את האירוע לכל היעדים בבקשה.

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

השלבים הבאים

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

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

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

הכנת היעדים

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

אירוע 1

אירוע 2

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

אירוע 1

אירוע 2

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

אירוע 1

אירוע 2

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

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

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

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

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

שליחת הבקשה

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

תגובות שגיאה

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

השלבים הבאים

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

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