Method: events.ingest

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

درخواست HTTP

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

این URL از سینتکس Transcoding در 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
}
فیلدها
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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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

اختیاری. مقدار تبدیل مرتبط با رویداد، برای تبدیل‌های مبتنی بر ارزش.

شناسه‌های تبلیغاتی

شناسه‌ها و سایر اطلاعات مورد استفاده برای تطبیق رویداد تبدیل با سایر فعالیت‌های آنلاین (مانند کلیک‌های تبلیغاتی).

نمایش JSON 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  },
  "mobileDeviceId": string
}
فیلدها
sessionAttributes

string

اختیاری. ویژگی‌های جلسه برای انتساب و مدل‌سازی رویداد.

gclid

string

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

gbraid

string

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

wbraid

string

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

landingPageDeviceInfo

object ( DeviceInfo )

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

mobileDeviceId

string

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

اطلاعات دستگاه

اطلاعات مربوط به دستگاهی که هنگام وقوع رویداد مورد استفاده قرار گرفته است (در صورت وجود).

نمایش 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 دستگاه برای زمینه داده شده.

توجه: گوگل ادز از تطبیق آدرس IP برای کاربران نهایی در منطقه اقتصادی اروپا (EEA)، بریتانیا (UK) یا سوئیس (CH) پشتیبانی نمی‌کند. منطقی اضافه کنید تا به طور مشروط اشتراک‌گذاری آدرس‌های IP را از کاربران این مناطق حذف کنید و اطمینان حاصل کنید که اطلاعات واضح و جامعی در مورد داده‌هایی که در سایت‌ها، برنامه‌ها و سایر دارایی‌های خود جمع‌آوری می‌کنید در اختیار کاربران قرار می‌دهید و در صورت لزوم طبق قانون یا هرگونه سیاست گوگل، رضایت آنها را دریافت می‌کنید. برای جزئیات بیشتر به صفحه «درباره واردات تبدیل آفلاین» مراجعه کنید.

category

string

اختیاری. دسته دستگاه. به عنوان مثال، "دسکتاپ"، "تبلت"، "موبایل"، "تلویزیون هوشمند".

languageCode

string

اختیاری. زبانی که دستگاه با فرمت ISO 639-1 استفاده می‌کند.

screenHeight

integer

اختیاری. ارتفاع صفحه نمایش بر حسب پیکسل.

screenWidth

integer

اختیاری. عرض صفحه نمایش بر حسب پیکسل.

operatingSystem

string

اختیاری. سیستم عامل یا پلتفرم دستگاه.

operatingSystemVersion

string

اختیاری. نسخه سیستم عامل یا پلتفرم.

model

string

اختیاری. مدل دستگاه.

brand

string

اختیاری. نام تجاری دستگاه.

browser

string

اختیاری. برند یا نوع مرورگر.

browserVersion

string

اختیاری. نسخه مرورگر.

منبع رویداد

منبع رویداد.

انوم‌ها
EVENT_SOURCE_UNSPECIFIED منبع رویداد نامشخص. هرگز نباید استفاده شود.
WEB این رویداد از یک مرورگر وب ایجاد شده است.
APP این رویداد از یک برنامه ایجاد شده است.
IN_STORE این رویداد از یک تراکنش درون فروشگاهی ایجاد شده است.
PHONE این رویداد از یک تماس تلفنی ایجاد شد.
MESSAGE این رویداد از یک پیام ایجاد شده است.
OTHER این رویداد از منابع دیگر تولید شده است.

سبد خرید

داده‌های سبد خرید مرتبط با رویداد.

نمایش JSON 
{
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "transactionDiscount": number,
  "items": [
    {
      object (Item)
    }
  ],
  "couponCodes": [
    string
  ]
}
فیلدها
merchantId

string

اختیاری. شناسه مرکز فروش مرتبط با اقلام.

merchantFeedLabel

string

اختیاری. برچسب فید مرکز فروشندگان که با فید اقلام مرتبط است.

merchantFeedLanguageCode

string

اختیاری. کد زبان در ISO 639-1 مرتبط با فید مرکز فروشندگان اقلام. جایی که اقلام شما آپلود می‌شوند.

transactionDiscount

number

اختیاری. مجموع تمام تخفیف‌های مرتبط با تراکنش.

items[]

object ( Item )

اختیاری. فهرست موارد مرتبط با رویداد.

couponCodes[]

string

اختیاری. فهرست کدهای تخفیفی که به سبد خرید اعمال شده‌اند. کدهای تخفیف سطح سبد خرید و سطح کالا مستقل هستند.

اگر رویداد مربوط به یک مقصد گوگل آنالیتیکس است، فقط یک کد تخفیف ارائه دهید. گوگل آنالیتیکس کدهای تخفیف اضافی را نادیده می‌گیرد.

مورد

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

نمایش 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

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

quantity

string ( int64 format)

اختیاری. شماره این آیتم مرتبط با رویداد.

unitPrice

number

اختیاری. قیمت واحد بدون احتساب مالیات، هزینه ارسال و هرگونه تخفیف در سطح تراکنش.

itemId

string

اختیاری. یک شناسه منحصر به فرد برای ارجاع به آیتم.

additionalItemParameters[]

object ( ItemParameter )

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

merchantId

string

اختیاری. شناسه مرکز فروشندگان مرتبط با کالا. برای رویدادهای فروش فروشگاه، این مقدار جایگزین مقدار تعیین شده در سطح سبد خرید می‌شود. این فیلد برای سایر رویدادها نادیده گرفته می‌شود.

merchantFeedLabel

string

اختیاری. برچسب فید مرکز فروشندگان. اگر هنوز از کشورها استفاده می‌شود، می‌توان از کد دو حرفی کشور در ISO-3166-1 alpha-2 استفاده کرد. برای رویدادهای فروش فروشگاه، این مقدار بر مقدار تعیین شده در سطح سبد خرید اولویت دارد. این فیلد برای سایر رویدادها نادیده گرفته می‌شود.

merchantFeedLanguageCode

string

اختیاری. کد زبان در ISO 639-1 مرتبط با فید مرکز فروشندگان که اقلام شما در آن آپلود می‌شوند.

customVariables[]

object ( ItemCustomVariable )

اختیاری. اطلاعات جفت کلید/مقدار اضافی برای ارسال به کانتینرهای تبدیل (عمل تبدیل یا فعالیت Floodlight)، هنگام ردیابی تبدیل‌های هر آیتم.

conversionValue

number

اختیاری. مقدار تبدیل مرتبط با این آیتم درون رویداد، برای مواردی که مقدار تبدیل برای هر آیتم متفاوت است.

پارامتر مورد

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

نمایش JSON 
{
  "parameterName": string,
  "value": string
}
فیلدها
parameterName

string

الزامی. نام پارامتری که قرار است استفاده شود.

value

string

الزامی. نمایش رشته‌ای مقدار پارامتری که قرار است تنظیم شود.

موردسفارشیمتغیر

متغیر سفارشی در سطح آیتم برای تبدیل تبلیغات.

نمایش JSON 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
فیلدها
variable

string

اختیاری. نام متغیر سفارشی که قرار است تنظیم شود. اگر متغیر برای مقصد داده شده پیدا نشود، نادیده گرفته می‌شود.

value

string

اختیاری. مقداری که قرار است برای متغیر سفارشی ذخیره شود.

destinationReferences[]

string

اختیاری. رشته مرجعی که برای تعیین اینکه متغیر سفارشی باید به کدام یک از Event.destination_references ارسال شود، استفاده می‌شود. در صورت خالی بودن، از Event.destination_references استفاده خواهد شد.

متغیر سفارشی

متغیر سفارشی برای تبدیل تبلیغات.

نمایش JSON 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
فیلدها
variable

string

اختیاری. نام متغیر سفارشی که قرار است تنظیم شود. اگر متغیر برای مقصد داده شده پیدا نشود، نادیده گرفته می‌شود.

value

string

اختیاری. مقداری که قرار است برای متغیر سفارشی ذخیره شود.

destinationReferences[]

string

اختیاری. رشته مرجعی که برای تعیین اینکه متغیر سفارشی باید به کدام یک از Event.destination_references ارسال شود، استفاده می‌شود. در صورت خالی بودن، از Event.destination_references استفاده خواهد شد.

میدان تجربی

میدان تجربی که نمایانگر میدان‌های غیررسمی است.

نمایش JSON 
{
  "field": string,
  "value": string
}
فیلدها
field

string

اختیاری. نام فیلدی که قرار است استفاده شود.

value

string

اختیاری. مقداری که فیلد باید تنظیم کند.

ویژگی‌های کاربر

اطلاعات ارزیابی‌شده توسط تبلیغ‌کننده درباره کاربر در زمان وقوع رویداد. برای جزئیات بیشتر به 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 )

اختیاری. مجموعه‌ای از هرگونه ویژگی کاربر اضافی برای کاربر مرتبط با این رویداد.

نوع مشتری

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

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

سبد ارزش مشتری

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

انوم‌ها
CUSTOMER_VALUE_BUCKET_UNSPECIFIED CustomerValueBucket نامشخص. هرگز نباید استفاده شود.
LOW مشتری ارزش پایینی دارد.
MEDIUM مشتری ارزش متوسطی دارد.
HIGH مشتری ارزش بالایی دارد.

ملک کاربری

مجموعه‌ای از هرگونه ویژگی اضافی کاربر برای کاربر مرتبط با این رویداد.

نمایش JSON 
{
  "propertyName": string,
  "value": string
}
فیلدها
propertyName

string

الزامی. نام ویژگی کاربری که قرار است استفاده شود.

value

string

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

پارامتر رویداد

پارامتر رویداد برای رویدادهای GA4.

نمایش JSON 
{
  "parameterName": string,
  "value": string
}
فیلدها
parameterName

string

الزامی. نام پارامتری که قرار است استفاده شود.

value

string

الزامی. نمایش رشته‌ای مقدار پارامتری که قرار است تنظیم شود.

محل رویداد

مکانی که رویداد در آن رخ داده است.

نمایش 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 که رویداد در آن رخ داده است.