Method: events.ingest

فهرست Event منبع را از Destination ارائه‌شده بارگذاری می‌کند.

درخواست HTTP

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

نشانی وب از نحو ترانویسی gRPC استفاده می‌کند.

متن درخواست

بدنه درخواست حاوی داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],
  "consent": {
    object (Consent)
  },
  "validateOnly": boolean,
  "encoding": enum (Encoding),
  "encryptionInfo": {
    object (EncryptionInfo)
  }
}
فیلدها
destinations[]

object (Destination)

الزامی. فهرست مقاصد برای ارسال رویدادها به آن‌ها.
events[]

object (Event)

الزامی. فهرست رویدادهایی که باید به مقصدهای مشخص‌شده ارسال شود. حداکثر ۲۰۰۰ منبع 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,
  "conversionValue": number,
  "conversionCount": number
}
فیلدها
destinationReferences[]

string

اختیاری. رشته مرجع مورداستفاده برای تعیین مقصد. اگر خالی باشد، رویداد به همه destinations در درخواست ارسال خواهد شد.
transactionId

string

اختیاری. شناسه یکتای این رویداد. برای رویدادهایی که به‌عنوان منبع داده اضافی برای تبدیل‌های برچسب ارسال می‌شوند لازم است.
eventTimestamp

string (Timestamp format)

الزامی. زمان وقوع رویداد.

از RFC 3339 استفاده می‌کند، که در آن برونداد تولیدشده همیشه Z-نرمال‌سازی می‌شود و از ۰، ۳، ۶، یا ۹ رقم کسری استفاده می‌کند. انحراف‌های غیر از «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-نرمال‌سازی می‌شود و از ۰، ۳، ۶، یا ۹ رقم کسری استفاده می‌کند. انحراف‌های غیر از «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)

اختیاری. فهرستی از جفت‌های کلید/مقدار برای فیلدهای آزمایشی که ممکن است درنهایت به بخشی از «میانای برنامه‌سازی کاربردی» ارتقا یابند.
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)
    }
  ],
  "ppid": string,
  "visitorPpid": string
}
فیلدها
sessionAttributes

string

اختیاری. مشخصه‌های جلسه برای مدل‌سازی و اسناد رویداد.
gclid

string

اختیاری. شناسه کلیک Google (gclid) مرتبط با این رویداد.
gbraid

string

اختیاری. شناسه کلیک برای کلیک‌های مرتبط با رویدادهای برنامه و نشئت‌گرفته از دستگاه‌های iOS که با iOS14 شروع می‌شود.
wbraid

string

اختیاری. شناسه کلیک برای کلیک‌های مرتبط با رویدادهای وب و نشئت‌گرفته از دستگاه‌های iOS که با iOS14 شروع می‌شود.
landingPageDeviceInfo

object (DeviceInfo)

اختیاری. اطلاعات جمع‌آوری‌شده درباره دستگاهی که (درصورت وجود) در زمان ورود به سایت تبلیغ‌کننده پس‌از تعامل با آگهی استفاده می‌شود.
mobileDeviceId

string

اختیاری. شناسه تلفن همراه برای تبلیغ‌کنندگان. این شناسه در iOS، شناسه تبلیغاتی در Android، یا شناسه‌های دیگر پلاتفرم‌ها برای تبلیغ‌کنندگان خواهد بود.
dclid

string

اختیاری. شناسه کلیک نمایشی مرتبط با این رویداد.
impressionId

string

اختیاری. شناسه ظهور مرتبط با این رویداد.
matchId

string

اختیاری. فیلد شناسه مطابقت که برای پیوستن این رویداد به رویداد قبلی استفاده می‌شود.
encryptedUserIds[]

object (EncryptedUserId)

اختیاری. هر تعداد شناسه کاربر رمزگذاری‌شده.
ppid

string

اختیاری. شناسه یکتای کاربر اصیل‌سازی‌شده (واردشده به سیستم)، همان‌گونه که ناشر تعریف کرده است.
visitorPpid

string

اختیاری. شناسه یکتا برای کاربر اصالت‌سنجی‌نشده (کاربری که به سیستم وارد نشده است)، همان‌گونه که ناشر تعریف کرده است.

EncryptedUserId

شناسه کاربری صادرشده برای استفاده در اسنادی. اگر از این مورد استفاده می‌کنید، همه فیلدها الزامی است.

نمایش JSON 
{
  "encryptedId": string,
  "entityType": enum (EncryptionEntityType),
  "entityId": string,
  "source": enum (EncryptionSource)
}
فیلدها
encryptedId

string

الزامی. شناسه رمزگذاری‌شده الفباعددی.
entityType

enum (EncryptionEntityType)

الزامی. نوع نهاد رمزگذاری. این باید با پیکربندی رمزگذاری برای ارائه آگهی یا «انتقال داده» مطابقت داشته باشد.
entityId

string (int64 format)

الزامی. شناسه نهاد رمزگذاری. این باید با پیکربندی رمزگذاری برای ارائه آگهی یا «انتقال داده» مطابقت داشته باشد.
source

enum (EncryptionSource)

الزامی. توضیح می‌دهد که آیا کوکی رمزگذاری‌شده از ارائه آگهی (کلان‌دستور %m) یا از «انتقال داده» دریافت شده است.

EncryptionEntityType

نوع نهاد رمزگذاری.

شمارشی‌ها
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

منبع رمزگذاری.

شمارشی‌ها
ENCRYPTION_SOURCE_UNSPECIFIED منبع رمزگذاری مشخص نشده است.
AD_SERVING منبع رمزگذاری ارائه آگهی.
DATA_TRANSFER منبع رمزگذاری انتقال داده.

EventSource

منبع رویداد.

شمارشی‌ها
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. اگر کشورها همچنان استفاده می‌شوند، می‌توان به‌جای آن از کد کشور ۲ حرفی در 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

نوع مشتری مرتبط با رویداد.

شمارشی‌ها
CUSTOMER_TYPE_UNSPECIFIED ‫CustomerType نامشخص. هرگز نباید استفاده شود.
NEW مشتری برای تبلیغ‌کننده جدید است.
RETURNING مشتری به آگهی‌دهنده برمی‌گردد.
REENGAGED مشتری با تبلیغ‌کننده دوباره تعامل برقرار کرده است.

CustomerValueBucket

مقدار مشتری که تبلیغ‌کننده ارزیابی کرده است.

شمارشی‌ها
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

اختیاری. کد منطقه CLDR دوحرفی نشانی کاربر.
subcontinentCode

string

اختیاری. کد زیرقاره در قالب UN M49 که رویداد در آن رخ داده است.
continentCode

string

اختیاری. کد قاره در قالب UN M49 که رویداد در آن رخ داده است.