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,
  "fieldWarnings": [
    {
      object (FieldWarning)
    }
  ]
}
שדות
requestId

string

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

object (FieldWarning)

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

היקפי הרשאות

נדרש היקף ההרשאות הבא של 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,
  "callInfo": {
    object (CallInfo)
  },
  "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)

אופציונלי. מידע נוסף על צמדי מפתח/ערך שצריך לשלוח למאגרי ההמרות (פעולת המרה או פעילות ב-Floodlight).
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.
callInfo

object (CallInfo)

אופציונלי. מידע שנאסף על השיחה (אם יש כזה) שהובילה לאירוע הזה.
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)
    }
  ],
  "ppid": string,
  "visitorPpid": string,
  "leadId": string
}
שדות
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)

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

string

אופציונלי. מזהה ייחודי של משתמש מאומת (מחובר לחשבון), כפי שהוגדר על ידי בעל האפליקציה.
visitorPpid

string

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

string

אופציונלי. מזהה שנוצר על ידי Google ומונפק כשמשתמש שולח טופס להשארת פרטים.

EncryptedUserId

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

ייצוג ב-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) או מהעברת נתונים.

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 לא צוין EventSource. אין להשתמש בהן אף פעם.
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 לא צוין 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 שבה האירוע התרחש.

CallInfo

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

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

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".