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)

اختياريّ. معلومات عن مفاتيح التشفير المستخدَمة لتشفير البيانات يجب توفير هذا الحقل عندما تحتوي أحداث الإعلانات على 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 مكتملة