Method: events.ingest

העלאה של רשימת משאבים Event מהקובץ Destination שסופק.

בקשת HTTP

POST https://datamanager.googleapis.com/v1/events:ingest

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],
  "consent": {
    object (Consent)
  },
  "validateOnly": boolean,
  "encoding": enum (Encoding),
  "encryptionInfo": {
    object (EncryptionInfo)
  }
}
שדות
destinations[]

object (Destination)

חובה. רשימת היעדים שאליהם יישלחו האירועים.
events[]

object (Event)

חובה. רשימת האירועים שיישלחו ליעדים שצוינו. אפשר לשלוח עד 2,000 משאבים מסוג Event בבקשה אחת.
consent

object (Consent)

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

boolean

אופציונלי. למטרות בדיקה. אם true, הבקשה מאומתת אבל לא מבוצעת. מוחזרות רק שגיאות, ולא תוצאות.
encoding

enum (Encoding)

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

object (EncryptionInfo)

אופציונלי. מידע על ההצפנה של העלאות ב-UserData. אם לא מוגדר, ההנחה היא שהפרטים האישיים המזהים שהועלו מגובבים אבל לא מוצפנים. אם לא מדובר בהעלאות של UserData, המערכת מתעלמת מהשדה הזה.

גוף התשובה

תגובה מIngestEventsRequest.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "requestId": string
}
שדות
requestId

string

המזהה שנוצר אוטומטית של הבקשה.

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/datamanager

אירוע

אירוע שמייצג אינטראקציה של משתמש עם אתר או אפליקציה של מפרסם.

ייצוג ב-JSON 
{
  "destinationReferences": [
    string
  ],
  "transactionId": string,
  "eventTimestamp": string,
  "lastUpdatedTimestamp": string,
  "userData": {
    object (UserData)
  },
  "consent": {
    object (Consent)
  },
  "adIdentifiers": {
    object (AdIdentifiers)
  },
  "currency": string,
  "eventSource": enum (EventSource),
  "eventDeviceInfo": {
    object (DeviceInfo)
  },
  "cartData": {
    object (CartData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "experimentalFields": [
    {
      object (ExperimentalField)
    }
  ],
  "userProperties": {
    object (UserProperties)
  },
  "eventName": string,
  "clientId": string,
  "userId": string,
  "additionalEventParameters": [
    {
      object (EventParameter)
    }
  ],
  "thirdPartyUserData": {
    object (UserData)
  },
  "eventLocation": {
    object (EventLocation)
  },
  "appInstanceId": string,
  "conversionValue": number
}
שדות
destinationReferences[]

string

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

string

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

string (Timestamp format)

חובה. השעה שבה האירוע התרחש.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
lastUpdatedTimestamp

string (Timestamp format)

אופציונלי. הפעם האחרונה שבה האירוע עודכן.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
userData

object (UserData)

אופציונלי. חלקים מפרטים שהמשתמשים סיפקו, שמייצגים את המשתמש שהאירוע משויך אליו.
consent

object (Consent)

אופציונלי. מידע על כך שהמשתמש המשויך סיפק סוגים שונים של הסכמה.
adIdentifiers

object (AdIdentifiers)

אופציונלי. מזהים ומידע אחר שמשמשים להתאמה של אירוע ההמרה לפעילות אונליין אחרת (כמו קליקים על מודעות).
currency

string

אופציונלי. קוד המטבע שמשויך לכל הערכים הכספיים באירוע הזה.
eventSource

enum (EventSource)

אופציונלי. אות שמציין איפה האירוע קרה (באינטרנט, באפליקציה, בחנות וכו').
eventDeviceInfo

object (DeviceInfo)

אופציונלי. מידע שנאסף על המכשיר שבו נעשה שימוש (אם בכלל) כשהאירוע קרה.
cartData

object (CartData)

אופציונלי. מידע על העסקה ועל הפריטים שמשויכים לאירוע.
customVariables[]

object (CustomVariable)

אופציונלי. מידע נוסף על זוגות של מפתח/ערך לשליחה למאגרי התגים של ההמרות (פעולת המרה או פעילות FL).
experimentalFields[]

object (ExperimentalField)

אופציונלי. רשימה של צמדי מפתח/ערך לשדות ניסיוניים שעשויים בסופו של דבר להיכלל ב-API.
userProperties

object (UserProperties)

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

string

אופציונלי. שם האירוע. חובה לאירועים ב-GA4.
clientId

string

אופציונלי. מזהה ייחודי של מופע המשתמש של לקוח אינטרנט במקור לנתוני האתר הזה של GA4.
userId

string

אופציונלי. מזהה ייחודי של משתמש, כפי שהוגדר על ידי המפרסם.
additionalEventParameters[]

object (EventParameter)

אופציונלי. מאגר של פרמטרים של אירועים שצריך לכלול באירוע, שלא צוינו כבר באמצעות שדות מובנים אחרים.
thirdPartyUserData

object (UserData)

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

object (EventLocation)

אופציונלי. מידע שנאסף על מיקום המשתמש בזמן שהאירוע הזה התרחש.
appInstanceId

string

אופציונלי. מזהה ייחודי של מופע המשתמש של לקוח אפליקציה במקור הנתונים הזה של האפליקציה ב-GA4.
conversionValue

number

אופציונלי. ערך ההמרה שמשויך לאירוע, להמרות מבוססות-ערך.

AdIdentifiers

מזהים ומידע אחר שמשמשים להתאמה של אירוע ההמרה לפעילות אונליין אחרת (כמו קליקים על מודעות).

ייצוג ב-JSON 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  },
  "mobileDeviceId": string
}
שדות
sessionAttributes

string

אופציונלי. מאפייני סשן לשיוך אירועים ולמודלים.
gclid

string

אופציונלי. מספר הקליק ב-Google‏ (gclid) שמשויך לאירוע הזה.
gbraid

string

אופציונלי. המזהה של קליקים שמשויכים לאירועים באפליקציה ומגיעים ממכשירי iOS בגרסה 14 ואילך.
wbraid

string

אופציונלי. המזהה של קליקים שמשויכים לאירועים באתר ומגיעים ממכשירי iOS בגרסה 14 ואילך.
landingPageDeviceInfo

object (DeviceInfo)

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

string

אופציונלי. המזהה לצורכי פרסום במובייל. המזהה הזה הוא IDFA ב-iOS,‏ AdID ב-Android או מזהים למפרסמים בפלטפורמות אחרות.

DeviceInfo

מידע על המכשיר שבו נעשה שימוש (אם יש כזה) כשהאירוע קרה.

ייצוג ב-JSON 
{
  "userAgent": string,
  "ipAddress": string,
  "category": string,
  "languageCode": string,
  "screenHeight": integer,
  "screenWidth": integer,
  "operatingSystem": string,
  "operatingSystemVersion": string,
  "model": string,
  "brand": string,
  "browser": string,
  "browserVersion": string
}
שדות
userAgent

string

אופציונלי. מחרוזת סוכן המשתמש של המכשיר בהקשר הנתון.
ipAddress

string

אופציונלי. כתובת ה-IP של המכשיר בהקשר הנתון.

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

string

אופציונלי. קטגוריית המכשיר. לדוגמה, 'מחשב', 'טאבלט', 'נייד', 'טלוויזיה חכמה'.
languageCode

string

אופציונלי. השפה שבה המכשיר משתמש בפורמט ISO 639-1.
screenHeight

integer

אופציונלי. גובה המסך בפיקסלים.
screenWidth

integer

אופציונלי. רוחב המסך בפיקסלים.
operatingSystem

string

אופציונלי. מערכת ההפעלה או הפלטפורמה של המכשיר.
operatingSystemVersion

string

אופציונלי. הגרסה של מערכת ההפעלה או הפלטפורמה.
model

string

אופציונלי. הדגם של המכשיר.
brand

string

אופציונלי. המותג של המכשיר.
browser

string

אופציונלי. המותג או הסוג של הדפדפן.
browserVersion

string

אופציונלי. גרסת הדפדפן.

EventSource

מקור האירוע.

טיפוסים בני מנייה (enum)
EVENT_SOURCE_UNSPECIFIED מקור האירוע לא צוין. אסור להשתמש בו.
WEB האירוע נוצר מדפדפן אינטרנט.
APP האירוע נוצר מאפליקציה.
IN_STORE האירוע נוצר מעסקה בחנות.
PHONE האירוע נוצר משיחת טלפון.
MESSAGE האירוע נוצר מהודעה.
OTHER האירוע נוצר ממקורות אחרים.

CartData

נתוני עגלת הקניות שמשויכים לאירוע.

ייצוג ב-JSON 
{
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "transactionDiscount": number,
  "items": [
    {
      object (Item)
    }
  ],
  "couponCodes": [
    string
  ]
}
שדות
merchantId

string

אופציונלי. מספר החשבון ב-Merchant Center שמשויך לפריטים.
merchantFeedLabel

string

אופציונלי. תווית הפיד ב-Merchant Center שמשויכת לפיד של הפריטים.
merchantFeedLanguageCode

string

אופציונלי. קוד השפה לפי תקן ISO 639-1 שמשויך לפיד ב-Merchant Center שאליו מועלים הפריטים.
transactionDiscount

number

אופציונלי. סכום כל ההנחות שמשויכות לעסקה.
items[]

object (Item)

אופציונלי. רשימת הפריטים שמשויכים לאירוע.
couponCodes[]

string

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

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

פריט

מייצג פריט בעגלת הקניות שמשויך לאירוע.

ייצוג ב-JSON 
{
  "merchantProductId": string,
  "quantity": string,
  "unitPrice": number,
  "itemId": string,
  "additionalItemParameters": [
    {
      object (ItemParameter)
    }
  ],
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "customVariables": [
    {
      object (ItemCustomVariable)
    }
  ],
  "conversionValue": number
}
שדות
merchantProductId

string

אופציונלי. מזהה המוצר בחשבון Merchant Center.
quantity

string (int64 format)

אופציונלי. מספר הפריט שמשויך לאירוע.
unitPrice

number

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

string

אופציונלי. מזהה ייחודי לציון הפריט.
additionalItemParameters[]

object (ItemParameter)

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

string

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

string

אופציונלי. תווית הפיד של פיד Merchant Center. אם עדיין נעשה שימוש במדינות, אפשר להשתמש במקום זאת בקוד המדינה בן 2 האותיות לפי תקן ISO-3166-1 alpha-2. באירועים של מכירות בחנות פיזית, הערך הזה יבטל את הערך שהוגדר ברמת עגלת הקניות. המערכת מתעלמת מהשדה הזה באירועים אחרים.
merchantFeedLanguageCode

string

אופציונלי. קוד השפה לפי תקן ISO 639-1 שמשויך לפיד ב-Merchant Center שאליו מועלים הפריטים.
customVariables[]

object (ItemCustomVariable)

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

number

אופציונלי. ערך ההמרה שמשויך לפריט הזה באירוע, במקרים שבהם ערך ההמרה שונה לכל פריט.

ItemParameter

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

ייצוג ב-JSON 
{
  "parameterName": string,
  "value": string
}
שדות
parameterName

string

חובה. שם הפרמטר שבו רוצים להשתמש.
value

string

חובה. הייצוג של ערך הפרמטר שרוצים להגדיר כמחרוזת.

ItemCustomVariable

משתנה מותאם אישית ברמת הפריט להמרות ממודעות.

ייצוג ב-JSON 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
שדות
variable

string

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

string

אופציונלי. הערך שרוצים לאחסן עבור המשתנה המותאם אישית.
destinationReferences[]

string

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

CustomVariable

משתנה מותאם אישית להמרות ממודעות.

ייצוג ב-JSON 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
שדות
variable

string

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

string

אופציונלי. הערך שרוצים לאחסן עבור המשתנה המותאם אישית.
destinationReferences[]

string

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

ExperimentalField

שדה ניסיוני שמייצג שדות לא רשמיים.

ייצוג ב-JSON 
{
  "field": string,
  "value": string
}
שדות
field

string

אופציונלי. שם השדה שבו רוצים להשתמש.
value

string

אופציונלי. הערך של השדה שרוצים להגדיר.

UserProperties

מידע שהמפרסם העריך לגבי המשתמש בזמן שהאירוע התרחש. פרטים נוספים זמינים בכתובת https://support.google.com/google-ads/answer/14007601.

ייצוג ב-JSON 
{
  "customerType": enum (CustomerType),
  "customerValueBucket": enum (CustomerValueBucket),
  "additionalUserProperties": [
    {
      object (UserProperty)
    }
  ]
}
שדות
customerType

enum (CustomerType)

אופציונלי. סוג הלקוח שמשויך לאירוע.
customerValueBucket

enum (CustomerValueBucket)

אופציונלי. הערך של הלקוח לפי הערכת המפרסם.
additionalUserProperties[]

object (UserProperty)

אופציונלי. מאגר של מאפייני משתמש נוספים שמשויכים למשתמש שקשור לאירוע הזה.

CustomerType

סוג הלקוח שמשויך לאירוע.

טיפוסים בני מנייה (enum)
CUSTOMER_TYPE_UNSPECIFIED לא צוין סוג לקוח. אסור להשתמש בו.
NEW הלקוח חדש עבור המפרסם.
RETURNING הלקוח חוזר אל המפרסם.
REENGAGED הלקוח יצר קשר מחדש עם המפרסם.

CustomerValueBucket

הערך של הלקוח לפי הערכת המפרסם.

טיפוסים בני מנייה (enum)
CUSTOMER_VALUE_BUCKET_UNSPECIFIED ‫Unspecified CustomerValueBucket. אסור להשתמש בו.
LOW הלקוח הוא בעל ערך נמוך.
MEDIUM הלקוח הוא בעל ערך בינוני.
HIGH הלקוח רווחי.

UserProperty

מאגר של מאפייני משתמש נוספים שמשויכים למשתמש שקשור לאירוע הזה.

ייצוג ב-JSON 
{
  "propertyName": string,
  "value": string
}
שדות
propertyName

string

חובה. השם של מאפיין המשתמש שבו רוצים להשתמש.
value

string

חובה. ייצוג המחרוזת של הערך של מאפיין המשתמש שבו רוצים להשתמש.

EventParameter

פרמטר של אירוע לאירועים ב-GA4.

ייצוג ב-JSON 
{
  "parameterName": string,
  "value": string
}
שדות
parameterName

string

חובה. שם הפרמטר שבו רוצים להשתמש.
value

string

חובה. הייצוג של ערך הפרמטר שרוצים להגדיר כמחרוזת.

EventLocation

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

ייצוג ב-JSON 
{
  "storeId": string,
  "city": string,
  "subdivisionCode": string,
  "regionCode": string,
  "subcontinentCode": string,
  "continentCode": string
}
שדות
storeId

string

אופציונלי. חובה לדיווח על מכירות בחנות. המזהה שמייצג חנות פיזית שבה התרחש האירוע.
city

string

אופציונלי. שם העיר שבה התרחש האירוע.
subdivisionCode

string

אופציונלי. קוד חלוקת המשנה לפי תקן ISO 3166-2 שבו התרחש האירוע.
regionCode

string

אופציונלי. קוד האזור בן 2 האותיות של כתובת המשתמש במאגר CLDR.
subcontinentCode

string

אופציונלי. קוד תת-היבשת בפורמט UN M49 שבה התרחש האירוע.
continentCode

string

אופציונלי. קוד היבשת בפורמט UN M49 שבה התרחש האירוע.