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,
  "conversionCount": 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

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

number

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

AdIdentifiers

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

ייצוג ב-JSON 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  },
  "mobileDeviceId": string,
  "dclid": string,
  "impressionId": string,
  "matchId": string,
  "encryptedUserIds": [
    {
      object (EncryptedUserId)
    }
  ]
}
שדות
sessionAttributes

string

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

string

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

string

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

string

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

object (DeviceInfo)

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

string

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

string

אופציונלי. מזהה הקליק ברשת המדיה שמשויך לאירוע הזה.
impressionId

string

אופציונלי. מזהה החשיפה שמשויך לאירוע הזה.
matchId

string

אופציונלי. השדה של מזהה ההתאמה שמשמש לצירוף האירוע הזה לאירוע קודם.
encryptedUserIds[]

object (EncryptedUserId)

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

EncryptedUserId

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

ייצוג ב-JSON 
{
  "encryptedId": string,
  "entityType": enum (EncryptionEntityType),
  "entityId": string,
  "source": enum (EncryptionSource)
}
שדות
encryptedId

string

חובה. המזהה המוצפן האלפאנומרי.
entityType

enum (EncryptionEntityType)

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

string (int64 format)

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

enum (EncryptionSource)

חובה. המימד מתאר אם קובץ ה-Cookie המוצפן התקבל מפרסום מודעות (פקודת המאקרו ‎ %m) או מ-Data Transfer.

EncryptionEntityType

סוג ישות ההצפנה.

טיפוסים בני מנייה (enum)
ENCRYPTION_ENTITY_TYPE_UNSPECIFIED סוג ישות ההצפנה לא צוין.
CAMPAIGN_MANAGER_ACCOUNT חשבון Campaign Manager 360.
CAMPAIGN_MANAGER_ADVERTISER מפרסם ב-Campaign Manager 360.
DISPLAY_VIDEO_PARTNER שותף ב-Display & Video 360.
DISPLAY_VIDEO_ADVERTISER מפרסם ב-Display & Video 360.
GOOGLE_ADS_CUSTOMER לקוח של Google Ads.
GOOGLE_AD_MANAGER_NETWORK_CODE קוד הרשת של Google Ad Manager.

EncryptionSource

מקור ההצפנה.

טיפוסים בני מנייה (enum)
ENCRYPTION_SOURCE_UNSPECIFIED מקור ההצפנה לא צוין.
AD_SERVING מקור ההצפנה של הצגת המודעות.
DATA_TRANSFER מקור ההצפנה של העברת הנתונים.

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 שבה התרחש האירוע.