Method: adEvents.ingest

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

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

طلب 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)

اختياريّ. معلومات عن مفاتيح التشفير المستخدَمة لتشفير البيانات
validateOnly

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)
  },
  "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)
  },

  // Union field event_subtype_oneof can be only one of the following:
  "eventSubtype": enum (EventSubtype),
  "eventSubtypeString": string
  // End of list of possible types for union field event_subtype_oneof.

  // Union field ad_type_oneof can be only one of the following:
  "adType": enum (AdType),
  "adTypeString": string
  // End of list of possible types for union field ad_type_oneof.

  // Union field ad_format_oneof can be only one of the following:
  "adFormat": enum (AdFormat),
  "adFormatString": string
  // End of list of possible types for union field ad_format_oneof.

  // Union field ad_placement_oneof can be only one of the following:
  "adPlacement": enum (AdPlacement),
  "adPlacementString": string
  // End of list of possible types for union field ad_placement_oneof.

  // Union field targeting_type_oneof can be only one of the following:
  "targetingType": enum (TargetingType),
  "targetingTypeString": string
  // End of list of possible types for union field targeting_type_oneof.

  // Union field platform_type_oneof can be only one of the following:
  "platformType": enum (PlatformType),
  "platformTypeString": string
  // End of list of possible types for union field platform_type_oneof.

  // Union field platform_oneof can be only one of the following:
  "platform": enum (Platform),
  "platformString": string
  // End of list of possible types for union field platform_oneof.
  "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)

اختياريّ. معلومات يتم جمعها عن الجهاز المستخدَم عند وقوع حدث الإعلان.
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)

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

حقل الربط event_subtype_oneof اختياريّ. تصنيف إضافي حول نوع حدث الإعلان.

يتم قبول سلسلة أولية للتعامل مع القيم بخلاف التعدادات النقية. يُفضَّل استخدام التعداد إذا كان ذلك ممكنًا. يمكن أن يكون التعليق event_subtype_oneof إحدى القيم التالية فقط:
eventSubtype

enum (EventSubtype)

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

string

قيمة السلسلة لنوع الحدث الفرعي.

حقل الربط ad_type_oneof اختياريّ. نوع الإعلان المعروض

يتم قبول سلسلة أولية للتعامل مع القيم بخلاف التعدادات النقية. يُفضَّل استخدام التعداد إذا كان ذلك ممكنًا. يمكن أن يكون التعليق ad_type_oneof إحدى القيم التالية فقط:
adType

enum (AdType)

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

string

قيمة السلسلة لنوع الإعلان.

حقل الربط ad_format_oneof اختياريّ. نوع الإعلان المعروض

يتم قبول سلسلة أولية للتعامل مع القيم بخلاف التعدادات النقية. يُفضَّل استخدام التعداد إذا كان ذلك ممكنًا. يمكن أن يكون التعليق ad_format_oneof إحدى القيم التالية فقط:
adFormat

enum (AdFormat)

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

string

قيمة السلسلة لشكل الإعلان.

حقل الربط ad_placement_oneof اختياريّ. موضع الإعلان المعروض

يتم قبول سلسلة أولية للتعامل مع القيم بخلاف التعدادات النقية. يُفضَّل استخدام التعداد إذا كان ذلك ممكنًا. يمكن أن يكون التعليق ad_placement_oneof إحدى القيم التالية فقط:
adPlacement

enum (AdPlacement)

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

string

قيمة السلسلة لموضع الإعلان

حقل الربط targeting_type_oneof اختياريّ. نوع الاستهداف المستخدَم لعرض الإعلان.

يتم قبول سلسلة أولية للتعامل مع القيم بخلاف التعدادات النقية. يُفضَّل استخدام التعداد إذا كان ذلك ممكنًا. يمكن أن يكون التعليق targeting_type_oneof إحدى القيم التالية فقط:
targetingType

enum (TargetingType)

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

string

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

حقل الربط platform_type_oneof اختياريّ. نوع النظام الأساسي الذي تم عرض الإعلان عليه.

يتم قبول سلسلة أولية للتعامل مع القيم بخلاف التعدادات النقية. يُفضَّل استخدام التعداد إذا كان ذلك ممكنًا. يمكن أن يكون التعليق platform_type_oneof إحدى القيم التالية فقط:
platformType

enum (PlatformType)

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

string

قيمة السلسلة لنوع النظام الأساسي

حقل الربط platform_oneof اختياريّ. تفاصيل إضافية عن المنصة التي تم عرض الإعلان عليها

يتم قبول سلسلة أولية للتعامل مع القيم بخلاف التعدادات النقية. يُفضَّل استخدام التعداد إذا كان ذلك ممكنًا. يمكن أن يكون التعليق platform_oneof إحدى القيم التالية فقط:
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 مكتملة