Method: adEvents.ingest

تحميل قائمة بموارد AdEvent إلى "إحصاءات Google"

هذه الميزة متاحة فقط للحسابات المُدرَجة في القائمة المسموح بها.

عناوين التفويض:

تتطلّب هذه الطريقة أيضًا العنوان التالي لتحديد كيفية منح واجهة برمجة التطبيقات إذن الوصول إلى الطلب:

  • ‫login-account: (مطلوب) اسم المورد لحساب "شريك البيانات" الذي يكون فيه حساب Google الخاص ببيانات الاعتماد مستخدمًا. التنسيق: accountTypes/DATA_PARTNER/accounts/{loginAccountId}

طلب HTTP

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

يستخدِم عنوان URL بنية تحويل الترميز إلى gRPC.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل JSON 
{
  "adEvents": [
    {
      object (AdEvent)
    }
  ],
  "encryptionInfo": {
    object (EncryptionInfo)
  },
  "validateOnly": boolean
}
الحقول
adEvents[]

object (AdEvent)

الحقل مطلوب. مطلوب (يجب توفير قيمة واحدة على الأقل). قائمة بأحداث الإعلانات
encryptionInfo

object (EncryptionInfo)

اختيارية: معلومات عن مفاتيح التشفير المستخدَمة لتشفير البيانات يجب توفير هذا الحقل عندما تحتوي أحداث الإعلانات على UserData.
validateOnly
(deprecated)

boolean

اختيارية: إذا كانت القيمة صحيحة، يتم التحقّق من صحة الطلب، ولكن لا يتم تنفيذه.

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيكون نصها فارغًا.

نطاقات الأذونات

يجب توفير نطاق OAuth التالي:

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

AdEvent

حدث إعلان

تمثيل JSON 
{
  "advertiserId": string,
  "eventType": enum (EventType),
  "timestamp": string,
  "eventId": string,
  "userData": {
    object (UserData)
  },
  "deviceInfo": {
    object (DeviceInfo)
  },
  "ipAddress": string,
  "mobileDeviceId": string,
  "campaignId": string,
  "campaignName": string,
  "adGroupId": string,
  "adId": string,
  "adHeight": integer,
  "adWidth": integer,
  "regionCode": string,
  "source": string,
  "medium": string,
  "attributionHint": enum (AttributionHint),
  "viewabilityInfo": {
    object (ViewabilityInfo)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "eventSubtype": enum (EventSubtype),
  "eventSubtypeString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "adType": enum (AdType),
  "adTypeString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "adFormat": enum (AdFormat),
  "adFormatString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "adPlacement": enum (AdPlacement),
  "adPlacementString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "targetingType": enum (TargetingType),
  "targetingTypeString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "platformType": enum (PlatformType),
  "platformTypeString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "platform": enum (Platform),
  "platformString": string
  // End of mutually exclusive fields.
  "measurementAllowed": boolean
}
الحقول
advertiserId

string

الحقل مطلوب. رقم تعريف المعلِن لحدث الإعلان.

يجب أن يتطابق هذا المعرّف مع المعرّف المُرسَل في عملية الربط.
eventType

enum (EventType)

الحقل مطلوب. تمثّل هذه السمة نوع الحدث.
timestamp

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

string

اختيارية: معرّف ينشئه المتصل ويديره ويحدّد هذا الحدث بشكل فريد.

مطلوب إذا كنت تريد إزالة تكرار أحداث الإعلانات المُدرَجة في طلبات متعدّدة. بخلاف ذلك، يكون هذا الحقل اختياريًا.
userData

object (UserData)

اختيارية: أجزاء متعدّدة من البيانات المقدَّمة من المستخدِم، وتمثّل المستخدِم المرتبط بالحدث.

يمكن تقديم عدة أمثلة على النوع نفسه من البيانات (مثل عنوان البريد الإلكتروني). كلّما زادت البيانات المقدَّمة، زاد احتمال العثور على تطابق.
deviceInfo

object (DeviceInfo)

الحقل مطلوب. معلومات يتم جمعها عن الجهاز المستخدَم عند وقوع حدث الإعلان.
ipAddress

string

اختيارية: عنوان IP المستخدَم للقياس يجب أن تكون هذه القيمة مماثلة لقيمة DeviceInfo.ip_address. اتركها فارغة إذا كنت لا تريد مشاركة عنوان IP لأغراض القياس.
mobileDeviceId

string

اختيارية: رقم تعريف الجهاز الذي تم عرض الإعلان عليه.
campaignId

string

الحقل مطلوب. رقم تعريف الحملة المرتبطة.
campaignName

string

الحقل مطلوب. اسم الحملة المرتبطة.
adGroupId

string

اختيارية: رقم تعريف المجموعة الإعلانية المرتبطة.
adId

string

اختيارية: رقم تعريف الإعلان المرتبط ضمن المجموعة.
adHeight

integer

اختيارية: ارتفاع الإعلان بالبكسل
adWidth

integer

اختيارية: تمثّل هذه السمة عرض الإعلان بالبكسل.
regionCode

string

اختيارية: تمثّل هذه السمة البلد والتقسيم الفرعي وفقًا لمعيار ISO 3166-2.
source

string

الحقل مطلوب. تمثّل هذه السمة مصدر المنصّة للإعلان، وهي مشابهة للمصدر في "إحصاءات Google".
medium

string

الحقل مطلوب. نوع الإعلان، وهو مشابه لنوع مصدر الزيارات في "إحصاءات Google".
attributionHint

enum (AttributionHint)

اختيارية: حالة تحديد المصدر التي يفترضها الشريك لحدث الإعلان هذا

ويعمل ذلك كإشارة فقط إلى كيفية تحديد المصدر من قِبل الشريك، ولا يفرض نتيجة نهائية في التقارير النهائية.
viewabilityInfo

object (ViewabilityInfo)

الحقل مطلوب. تفاصيل حول إمكانية عرض الإعلان المعروض

اختيارية: تصنيف إضافي حول نوع حدث الإعلان.

يتم قبول سلسلة أولية للتعامل مع القيم غير التعدادات النقية. يُفضَّل استخدام التعداد إذا أمكن ذلك. في ما يلي قائمة بالحقول التي يستبعد كلّ منها الآخر. سيتم ضبط حقل واحد على الأكثر في الردّ:
eventSubtype

enum (EventSubtype)

قيمة التعداد للنوع الفرعي للحدث
eventSubtypeString

string

قيمة السلسلة للنوع الفرعي للحدث
نهاية الحقول التي يستبعد كلّ منها الآخر

اختيارية: نوع الإعلان المعروض

يتم قبول سلسلة أولية للتعامل مع القيم غير التعدادات النقية. يُفضَّل استخدام التعداد إذا أمكن ذلك. في ما يلي قائمة بالحقول التي يستبعد كلّ منها الآخر. سيتم ضبط حقل واحد على الأكثر في الردّ:
adType

enum (AdType)

قيمة التعداد لنوع الإعلان.
adTypeString

string

قيمة السلسلة لنوع الإعلان.
نهاية الحقول التي يستبعد كلّ منها الآخر

اختيارية: نوع الإعلان المعروض

يتم قبول سلسلة أولية للتعامل مع القيم غير التعدادات النقية. يُفضَّل استخدام التعداد إذا أمكن ذلك. في ما يلي قائمة بالحقول التي يستبعد كلّ منها الآخر. سيتم ضبط حقل واحد على الأكثر في الردّ:
adFormat

enum (AdFormat)

قيمة التعداد لشكل الإعلان.
adFormatString

string

قيمة السلسلة لشكل الإعلان.
نهاية الحقول التي يستبعد كلّ منها الآخر

اختيارية: موضع الإعلان الذي تم عرضه

يتم قبول سلسلة أولية للتعامل مع القيم غير التعدادات النقية. يُفضَّل استخدام التعداد إذا أمكن ذلك. في ما يلي قائمة بالحقول التي يستبعد كلّ منها الآخر. سيتم ضبط حقل واحد على الأكثر في الردّ:
adPlacement

enum (AdPlacement)

قيمة التعداد لموضع الإعلان
adPlacementString

string

قيمة السلسلة لموضع الإعلان
نهاية الحقول التي يستبعد كلّ منها الآخر

اختيارية: نوع الاستهداف المستخدَم لعرض الإعلان.

يتم قبول سلسلة أولية للتعامل مع القيم غير التعدادات النقية. يُفضَّل استخدام التعداد إذا أمكن ذلك. في ما يلي قائمة بالحقول التي يستبعد كلّ منها الآخر. سيتم ضبط حقل واحد على الأكثر في الردّ:
targetingType

enum (TargetingType)

قيمة التعداد لنوع الاستهداف.
targetingTypeString

string

قيمة السلسلة لنوع الاستهداف.
نهاية الحقول التي يستبعد كلّ منها الآخر

اختيارية: نوع المنصة التي تم عرض الإعلان عليها.

يتم قبول سلسلة أولية للتعامل مع القيم غير التعدادات النقية. يُفضَّل استخدام التعداد إذا أمكن ذلك. في ما يلي قائمة بالحقول التي يستبعد كلّ منها الآخر. سيتم ضبط حقل واحد على الأكثر في الردّ:
platformType

enum (PlatformType)

قيمة التعداد لنوع المنصة
platformTypeString

string

قيمة السلسلة لنوع النظام الأساسي
نهاية الحقول التي يستبعد كلّ منها الآخر

اختيارية: تفاصيل إضافية عن المنصة التي تم عرض الإعلان عليها

يتم قبول سلسلة أولية للتعامل مع القيم غير التعدادات النقية. يُفضَّل استخدام التعداد إذا أمكن ذلك. في ما يلي قائمة بالحقول التي يستبعد كلّ منها الآخر. سيتم ضبط حقل واحد على الأكثر في الردّ:
platform

enum (Platform)

قيمة التعداد للمنصة
platformString

string

قيمة السلسلة للنظام الأساسي
نهاية الحقول التي يستبعد كلّ منها الآخر
measurementAllowed

boolean

اختيارية: توضّح هذه السمة ما إذا كان يُسمح باستخدام الصف لأغراض القياس، وذلك وفقًا لقوانين الخصوصية السارية ضمن الاختصاص الإقليمي.

EventType

تمثّل هذه السمة نوع الحدث.

عمليات التعداد
EVENT_TYPE_UNSPECIFIED نوع حدث غير محدَّد.
EVENT_TYPE_VIEW عرض الحدث
EVENT_TYPE_CLICK حدث ناتج عن النقر.

EventSubtype

تصنيف إضافي حول نوع حدث الإعلان.

عمليات التعداد
EVENT_SUBTYPE_UNSPECIFIED نوع فرعي غير محدّد للحدث
EVENT_SUBTYPE_IMPRESSION حدث ظهور الإعلان
EVENT_SUBTYPE_ENGAGED_VIEW حدث المشاهدة المطوّلة
EVENT_SUBTYPE_ONSITE_CLICK حدث ناتج عن النقر على الموقع الإلكتروني
EVENT_SUBTYPE_OUTBOUND_CLICK حدث ناتج عن نقرة تؤدي إلى خارج النطاق

AdType

نوع الإعلان المعروض

عمليات التعداد
AD_TYPE_UNSPECIFIED نوع الإعلان غير محدَّد.
AD_TYPE_DISPLAY إعلان صوري
AD_TYPE_TEXT إعلان نصي.
AD_TYPE_IMAGE إعلان صوريّ.
AD_TYPE_RICH_MEDIA إعلان وسائط تفاعلية متقدّمة
AD_TYPE_HTML إعلان HTML
AD_TYPE_AUDIO إعلان صوتي
AD_TYPE_VIDEO إعلان فيديو.

AdFormat

تمثّل هذه السمة شكل الإعلان الذي تم عرضه.

عمليات التعداد
AD_FORMAT_UNSPECIFIED شكل الإعلان غير محدّد.
AD_FORMAT_AR إعلان يتضمّن الواقع المعزّز
AD_FORMAT_AUDIO إعلان صوتي
AD_FORMAT_BANNER إعلان بانر
AD_FORMAT_BUMPER إعلان ملصق صغير
AD_FORMAT_COLLECTION إعلان المجموعة
AD_FORMAT_IMAGE إعلان صوريّ.
AD_FORMAT_INTERACTIVE إعلان تفاعلي
AD_FORMAT_INTERSTITIAL إعلان بيني
AD_FORMAT_IN_FEED إعلان ضمن الخلاصة
AD_FORMAT_IN_STREAM إعلان أثناء عرض الفيديو
AD_FORMAT_IN_STREAM_SKIPPABLE إعلان قابل للتخطّي أثناء عرض الفيديو
AD_FORMAT_IN_STREAM_NON_SKIPPABLE إعلان غير قابل للتخطّي أثناء عرض الفيديو
AD_FORMAT_NATIVE إعلان مدمج مع المحتوى
AD_FORMAT_SHORTS إعلان على Shorts
AD_FORMAT_STORY إعلان على شكل قصة
AD_FORMAT_SPONSORED إعلان دعائي
AD_FORMAT_VIDEO إعلان فيديو.

AdPlacement

موضع الإعلان الذي تم عرضه

عمليات التعداد
AD_PLACEMENT_UNSPECIFIED موضع الإعلان غير محدّد
AD_PLACEMENT_DISCOVER موضع الإعلان على "اكتشف"
AD_PLACEMENT_FEED موضع الخلاصة
AD_PLACEMENT_HEADER موضع العنوان
AD_PLACEMENT_HOME موضع الإعلان على الصفحة الرئيسية
AD_PLACEMENT_IN_CONTENT موضع الإعلان داخل المحتوى
AD_PLACEMENT_PROMOTED موضع إعلان تم الترويج له
AD_PLACEMENT_STORY موضع القصة

TargetingType

نوع الاستهداف المستخدَم لعرض الإعلان.

عمليات التعداد
TARGETING_TYPE_UNSPECIFIED نوع استهداف غير محدَّد
TARGETING_TYPE_AUDIENCE استهداف الجمهور
TARGETING_TYPE_CONTEXTUAL استهداف المحتوى:
TARGETING_TYPE_DEMOGRAPHIC استهداف الفئات الديمغرافية
TARGETING_TYPE_DEVICE استهداف الأجهزة:
TARGETING_TYPE_GEO الاستهداف الجغرافي
TARGETING_TYPE_INTEREST استهداف الاهتمامات:
TARGETING_TYPE_PURCHASE_INTENT استهداف الرغبة في الشراء
TARGETING_TYPE_REMARKETING استهداف تجديد النشاط التسويقي

PlatformType

نوع المنصة التي تم عرض الإعلان عليها.

عمليات التعداد
PLATFORM_TYPE_UNSPECIFIED نوع المنصة غير محدَّد.
PLATFORM_TYPE_MOBILE النظام الأساسي للأجهزة الجوّالة
PLATFORM_TYPE_DESKTOP النظام الأساسي لجهاز كمبيوتر سطح المكتب
PLATFORM_TYPE_CTV منصّة التلفزيون المتّصل
PLATFORM_TYPE_PHONE النظام الأساسي للهاتف
PLATFORM_TYPE_TABLET منصّة الأجهزة اللوحية

النظام الأساسي

تفاصيل إضافية عن المنصة التي تم عرض الإعلان عليها

عمليات التعداد
PLATFORM_UNSPECIFIED نظام أساسي غير محدّد
PLATFORM_IOS نظام التشغيل iOS
PLATFORM_ANDROID نظام Android الأساسي
PLATFORM_WEB النظام الأساسي على الويب

AttributionHint

حالة تحديد المصدر التي يفترضها الشريك لحدث الإعلان هذا

عمليات التعداد
ATTRIBUTION_HINT_UNSPECIFIED حالة تحديد المصدر غير معروفة.
ATTRIBUTION_HINT_CONVERTED الحالة التي تم تحويلها
ATTRIBUTION_HINT_NOT_CONVERTED الحالة "لم يتمّ التحويل"

ViewabilityInfo

تفاصيل حول إمكانية عرض الإعلان المعروض

تمثيل JSON 
{
  "viewType": enum (ViewType),
  "viewablePercent": integer,
  "viewableDuration": string,
  "mediaSkippable": boolean,
  "mediaQuartile": enum (MediaQuartile),
  "mediaDuration": string,
  "mediaVolumePercent": integer,
  "playbackDuration": string
}
الحقول
viewType

enum (ViewType)

الحقل مطلوب. تمثّل هذه السمة نوع الحدث.
viewablePercent

integer

اختيارية: النسبة المئوية الرقمية (من 0 إلى 100) لوحدات البكسل التي كانت قابلة للعرض.
viewableDuration

string (Duration format)

اختيارية: مقدار الوقت الذي كان فيه الإعلان قابلاً للعرض

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s".
mediaSkippable

boolean

اختيارية: تُستخدَم لتحديد ما إذا كانت وسائط الإعلان قابلة للتخطّي أم لا.
mediaQuartile

enum (MediaQuartile)

اختيارية: تمثّل هذه السمة مقدار الوسائط التي تم تشغيلها كشرائح ربعية منفصلة.
mediaDuration

string (Duration format)

اختيارية: مدة وسائط الإعلان

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s".
mediaVolumePercent

integer

اختيارية: النسبة المئوية العددية (من 0 إلى 100) لمستوى صوت تشغيل الوسائط
playbackDuration

string (Duration format)

اختيارية: مدة تشغيل وسائط الإعلان، بغض النظر عمّا إذا كان الإعلان قابلاً للعرض أم لا

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s".

ViewType

تمثّل هذه السمة نوع الحدث.

عمليات التعداد
VIEW_TYPE_UNSPECIFIED نوع العرض غير محدَّد.
VIEW_TYPE_MRC_VIEWED تمت مشاهدة MRC.
VIEW_TYPE_MRC_RENDERED تم عرض MRC.

MediaQuartile

تمثّل هذه السمة مقدار الوسائط التي تم تشغيلها كشرائح ربعية منفصلة.

عمليات التعداد
MEDIA_QUARTILE_UNSPECIFIED الربيعي غير المحدّد للوسائط
MEDIA_QUARTILE_START زر البدء:
MEDIA_QUARTILE_FIRST_QUARTILE الربع الأول
MEDIA_QUARTILE_MIDPOINT المنتصف
MEDIA_QUARTILE_THIRD_QUARTILE الربع الثالث
MEDIA_QUARTILE_COMPLETE مكتملة