واجهة برمجة التطبيقات المجدوَلة لإدراج الإعلانات الديناميكية

تتيح لك واجهة برمجة التطبيقات Dynamic Ad Insertion API طلب ميزة "إدراج إعلان ديناميكي" وتتبُّعها أحداث البث المباشر غير القابلة للتقديم أو الإيقاف

الخدمة: dai.google.com

ترتبط كل معرّفات الموارد المنتظمة (URI) التالية بالموقع الإلكتروني https://dai.google.com.

الطريقة: ساحة المشاركات

الطُرق
stream POST /linear/v1/hls/event/{assetKey}/stream

ينشئ هذا الإعداد ساحة مشاركات DAI لمعرّف الحدث المحدّد.

طلب HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

عنوان الطلب

المعلمات
api‑key string

مفتاح واجهة برمجة التطبيقات الذي يتم تقديمه عند إنشاء بث أن تكون صالحة لشبكة الناشر.

يمكن تمرير مفتاح واجهة برمجة التطبيقات بدلاً من توفيره في نص الطلب في عنوان تفويض HTTP بالتنسيق التالي:

Authorization: DCLKDAI key="<api-key>"

مَعلمات المسار

المعلمات
assetKey string

رقم تعريف حدث البث
ملاحظة: مفتاح مادة عرض البث هو معرّف يمكن العثور عليه أيضًا في واجهة مستخدم "مدير إعلانات Google".

نص الطلب

نص الطلب من النوع application/x-www-form-urlencoded ويحتوي على المَعلمات التالية:

المعلمات
dai-ssb اختياري

اضبط القيمة على true لإنشاء بث إشارة من جهة الخادم. وتكون القيمة التلقائية هي false. تتبُّع البث التلقائي يبدأها العميل ويرسل اختبار الاتصال من جهة الخادم.

مَعلمات الاستهداف في DDEX اختياري مَعلمات الاستهداف الإضافية
إلغاء مَعلمات البث اختياري إلغاء القيم التلقائية لمَعلمة إنشاء مصدر بيانات
مصادقة HMAC اختياري عليك المصادقة باستخدام رمز مميّز مستند إلى بروتوكول HMAC.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على Stream بالنسبة إلى أحداث البث التي تقدِّم إشارات من جهة الخادم، إنّ حدث Stream هذا يحتوي على الحقلين stream_id وstream_manifest فقط.

فتح القياس

تحتوي DAI API على معلومات لإثبات صحة بيانات القياس المفتوح في Verifications. يحتوي هذا الحقل على حقل واحد أو أكثر عناصر Verification التي تسرد الموارد والبيانات الوصفية المطلوبة للتنفيذ رمز القياس التابع لجهة خارجية للتحقّق من تشغيل المواد الإبداعية. فقط يُسمح باستخدام JavaScriptResource. لمزيد من المعلومات، يُرجى الاطّلاع على مختبر IAB التقني مواصفات VAST 4.1:

الطريقة: التحقق من الوسائط

بعد العثور على معرّف لوسائط الإعلانات أثناء التشغيل، طلب باستخدام media_verification_url التي تم الحصول عليها من ساحة المشاركات نقطة نهاية أعلى. هذه الطلبات ليست ضرورية لإجراء إشارة من جهة الخادم عمليات البث، حيث يبدأ الخادم التحقق من الوسائط.

الطلبات المُرسَلة إلى نقطة النهاية media verification ثابتة.

الطُرق
media verification GET /{media_verification_url}/{ad_media_id}

يتم إرسال إشعار إلى واجهة برمجة التطبيقات بحدث إثبات ملكية الوسائط.

طلب HTTP

GET https://{media-verification-url}/{ad-media-id}

نص الاستجابة

media verification تُرجع الإجابات التالية:

  • HTTP/1.1 204 No Content إذا تم التحقق من الوسائط بنجاح وتم إرسال كل الإشعارات.
  • HTTP/1.1 404 Not Found إذا تعذّر على الطلب التحقق من الوسائط بسبب تنسيق عنوان URL غير صحيح أو بسبب انتهاء الصلاحية.
  • HTTP/1.1 404 Not Found إذا نجح طلب إثبات الهوية السابق لمستند التعريف هذا.
  • HTTP/1.1 409 Conflict إذا كان هناك طلب آخر يرسل إشعارات في الوقت الحالي.

أرقام تعريف وسائط الإعلانات (HLS)

سيتم ترميز معرّفات وسائط الإعلانات في البيانات الوصفية المستندة إلى HLS باستخدام المفتاح TXXX، محجوز لـ "معلومات النص التي يحددها المستخدم" الإطارات. تشير رسالة الأشكال البيانية سيتم فك تشفير محتوى الإطار وسيبدأ دائمًا بالنص "google_"

يجب إلحاق المحتوى النصي الكامل للإطار بعملية التحقق من الإعلان. عنوان URL قبل تقديم كل طلب من طلبات التحقق من الإعلانات.

الطريقة: البيانات الوصفية

تعرض نقطة نهاية البيانات الوصفية في metadata_url المعلومات المستخدمة لإنشاء إعلان واجهة مستخدم لا تتوفر نقطة نهاية البيانات الوصفية لعمليات البث التي تتم الإشارة من جهة الخادم إليها، يكون فيها الخادم مسؤولاً عن بدء عملية التحقّق من وسائط الإعلانات.

الطُرق
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

يسترد معلومات البيانات الوصفية للإعلان.

طلب HTTP

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

نص الاستجابة

إذا كانت الاستجابة ناجحة، فستعرض الاستجابة مثيل PodMetadata

العمل باستخدام بيانات التعريف

تتألف البيانات الوصفية من ثلاثة أقسام منفصلة: tags وads والإعلان breaks. الإدخال البيانات هي القسم tags. بعد ذلك، كرِّر العلامات وأبحث عن الإدخال الأول الذي يكون اسمه بادئة معرّف وسائط الإعلانات الذي تم العثور عليه في الفيديو المضمّن. على سبيل المثال، رقم تعريف وسائط إعلان يبدو كالتالي:

google_1234567890

بعد ذلك، ستجد عنصر علامة باسم google_12345. في هذه الحالة، يتطابق مع الرقم التعريفي للوسائط الإعلانية بعد العثور على عنصر بادئة الوسائط الإعلانية الصحيح، يمكنك البحث وأرقام تعريف الإعلانات، وأرقام تعريف الفواصل الإعلانية، ونوع الحدث. بعد ذلك، يتم استخدام الأرقام التعريفية للإعلانات لفهرسة تُستخدَم كائنات ads وأرقام تعريف الفواصل الإعلانية لفهرسة كائنات breaks.

بيانات الاستجابة

بث

تُستخدَم ساحة المشاركات لعرض قائمة بالموارد لبث تم إنشاؤه حديثًا في تنسيق JSON.
تمثيل JSON
{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}
الحقول
stream_id string

معرّف مصدر البيانات في "مدير إعلانات Google"
stream_manifest string

عنوان URL الخاص ببيان البث، ويُستخدَم لاسترداد قائمة التشغيل ذات المتغيرات المتعددة في HLS أو MPD في DASH
hls_master_playlist string

(DEPRECATED) عنوان URL لقائمة تشغيل HLS متعددة المتغيرات. استخدام "stream_manifest" بدلاً من ذلك.
media_verification_url string

عنوان URL للتحقق من الوسائط المستخدَم كنقطة نهاية أساسية لتتبُّع أحداث التشغيل
metadata_url string

عنوان URL للبيانات الوصفية يتم استخدامه لإجراء استطلاع للحصول على المعلومات الدورية حول أحداث إعلانات البث القادمة.
session_update_url string

عنوان URL لتعديل الجلسة المستخدَم لتعديل مَعلمات الاستهداف لمصدر البيانات هذا. يتم تسجيل القيم الأصلية لمَعلمات الاستهداف أثناء طلب إنشاء البث الأوّلي.
polling_frequency number

معدّل تكرار الاستطلاع بالثواني عند طلب البيانات الوصفية_url أو Heartbeat_url.

PodMetadata

تحتوي PodMetadata على معلومات وصفية حول الإعلانات والفواصل الإعلانية وعلامات تعريف الوسائط.
تمثيل JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
الحقول
tags map[string, object(TagSegment)]

خريطة لأجزاء العلامة التي تمت فهرستها حسب بادئة العلامة
ads map[string, object(Ad)]

خريطة الإعلانات المفهرَسة حسب رقم تعريف الإعلان
ad_breaks map[string, object(AdBreak)]

خريطة الفواصل الإعلانية المفهرَسة حسب رقم تعريف الفاصل الإعلاني

TagSegment

تحتوي TagSegment على إشارة إلى أحد الإعلانات وفاصله الإعلاني ونوع الحدث. TagSegment with type="progress" يجب عدم إرسال إشعار إلى وسائط الإعلانات بنقطة نهاية التحقق.
تمثيل JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
الحقول
ad string

رقم تعريف إعلان هذه العلامة.
ad_break_id string

رقم تعريف الفاصل الإعلاني لهذه العلامة.
type string

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

AdBreak

تصف AdBreak فاصلاً إعلانيًا واحدًا في البث. فهي تحتوي على مدة نوع (منتصف/قبل/بعد) وعدد الإعلانات.
تمثيل JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
الحقول
type string

أنواع الفواصل الصالحة هي: قبل أو متوسط أو نشر.
duration number

إجمالي مدة الإعلان لهذا الفاصل الإعلاني بالثواني.
expected_duration number

مدة الفاصل الإعلاني المتوقّعة (بالثواني)، بما في ذلك جميع الإعلانات وأي عنصر حاجب.
ads number

عدد الإعلانات في الفاصل الإعلاني
يصف الإعلان إعلانًا أثناء البث.
تمثيل JSON
{
  "ad_break_id": string,
  "position": number,
  "duration": number,
  "title": string,
  "description": string,
  "advertiser": string,
  "ad_system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
  "clickthrough_url": string,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
الحقول
ad_break_id string

رقم تعريف الفاصل الإعلاني لهذا الإعلان.
position number

موضع هذا الإعلان في الفاصل الإعلاني، بدءًا من 1
duration number

مدة الإعلان بالثواني.
title string

عنوان اختياري للإعلان.
description string

وصف اختياري للإعلان.
advertiser string

المعرّف الاختياري للمعلِن:
ad_system string

نظام إعلانات اختياري:
ad_id string

رقم تعريف الإعلان الاختياري
creative_id string

رقم تعريف تصميم الإعلان الاختياري
creative_ad_id string

رقم تعريف إعلان تصميم الإعلان الاختياري
deal_id string

رقم تعريف الصفقة الاختيارية:
clickthrough_url string

عنوان URL اختياري لنسبة النقر إلى الظهور
click_tracking_urls string

عناوين URL اختيارية لتتبُّع النقرات
verifications [object(Verification)]

إدخالات اختيارية لتأكيد عملية القياس المفتوح تسرد الموارد والبيانات الوصفية المطلوبة لتنفيذ رمز القياس التابع لجهة خارجية من أجل التأكّد تشغيل المواد الإبداعية
slate boolean

قيمة منطقية اختيارية تشير إلى أنّ الإدخال الحالي هو عنصر حاجب.
icons [object(Icon)]

قائمة بالرموز، يتم حذفها إذا كانت فارغة:
wrappers [object(Wrapper)]

قائمة ببرامج الالتفاف، يتم حذفها إذا كانت فارغة.
universal_ad_id object(UniversalAdID)

رقم تعريف الإعلان العام الاختياري:
extensions string

قائمة اختيارية بجميع <الإضافة> في نموذج عرض إعلانات الفيديو (VAST)
companions [object(Companion)]

الإعلانات المصاحبة الاختيارية التي يمكن عرضها مع هذا الإعلان.
interactive_file object(InteractiveFile)

تصميم الإعلان التفاعلي الاختياري (SIMID) الذي يجب عرضه أثناء تشغيل الإعلان

الرمز

يحتوي الرمز على معلومات حول رمز نموذج عرض إعلانات فيديو (VAST).
تمثيل JSON
{
  "click_data": object(ClickData),
  "creative_type": string,
  "click_fallback_images": [object(FallbackImage)],
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "x_position": string,
  "y_position": string,
  "program": string,
  "alt_text": string,
}
الحقول
click_data object(ClickData)

creative_type string

click_fallback_images [object(FallbackImage)]

height int32

width int32

resource string

type string

x_position string

y_position string

program string

alt_text string

ClickData

تحتوي ClickData على معلومات حول النقر إلى أحد الرموز.
تمثيل JSON
{
  "url": string,
}
الحقول
url string

FallbackImage

تحتوي صورة FallbackImage على معلومات حول صورة VAST الاحتياطية.
تمثيل JSON
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
الحقول
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

يحتوي برنامج الغلاف على معلومات عن إعلان برنامج تضمين. لا يتضمّن رقم تعريف الصفقة إذا لم يكن متوفّرًا.
تمثيل JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
الحقول
system string

معرّف نظام الإعلانات:
ad_id string

رقم تعريف الإعلان المستخدَم لإعلان تضمين
creative_id string

رقم تعريف تصميم الإعلان المستخدَم لإعلان تضمين
creative_ad_id string

رقم تعريف تصميم الإعلان المستخدَم في الإعلان المضمّن
deal_id string

رقم تعريف الصفقة الاختياري لإعلان التضمين.

التحقّق

تحتوي عملية إثبات الملكية على معلومات حول "القياس المفتوح" الذي يسهّل قياس إمكانية العرض والتحقق من جهة خارجية. في الوقت الحالي، تتوفّر موارد JavaScript فقط. يُرجى الاطّلاع على https://iabtechlab.com/standards/open-measurement-sdk/ .
تمثيل JSON
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
الحقول
vendor string

مورّد إثبات الملكية:
java_script_resources [object(JavaScriptResource)]

قائمة بمصادر JavaScript لإثبات الهوية
tracking_events [object(TrackingEvent)]

قائمة بأحداث تتبُّع عملية إثبات الهوية
parameters string

يتم ضبط سلسلة مبهمة إلى رمز التحقّق من جهاز تمهيد التشغيل.

JavaScriptResource

يحتوي JavaScriptResource على معلومات لإثبات الهوية باستخدام JavaScript.
تمثيل JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
الحقول
script_url string

معرّف الموارد المنتظم (URI) لحمولة JavaScript
api_framework string

APIFramework هو اسم إطار عمل الفيديو الذي يمارس رمز إثبات الهوية
browser_optional boolean

ما إذا كان من الممكن تشغيل هذا النص البرمجي خارج

TrackingEvent

يحتوي TrackEvent على عناوين URL يجب أن يرسلها العميل بطريقة محدّدة المواقف المختلفة.
تمثيل JSON
{
  "event": string,
  "uri": string,
}
الحقول
event string

نوع حدث التتبُّع
uri string

حدث التتبُّع المطلوب إرسال إشارة إليه.

UniversalAdID

يتمّ استخدام UniversalAdID لتوفير معرّف فريد لتصميم الإعلان تتم صيانتها على جميع أنظمة الإعلانات
تمثيل JSON
{
  "id_value": string,
  "id_registry": string,
}
الحقول
id_value string

رقم تعريف الإعلان العام لتصميم الإعلان المحدّد.
id_registry string

سلسلة تُستخدَم لتحديد عنوان URL لموقع قاعدة بيانات المسجّلين حيث تمت فهرسة رقم تعريف الإعلان العام لتصميم الإعلان الذي اخترته.

الإعلان المصاحب

يحتوي الإعلان المصاحب على معلومات حول الإعلانات المصاحبة التي قد يتم عرضها. إلى جانب الإعلان.
تمثيل JSON
{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}
الحقول
click_data object(ClickData)

بيانات النقرات لهذا الإعلان المصاحب.
creative_type string

سمة CreativeType على <StaticResource> في VAST إذا كان فهذا إعلان مصاحب من النوع الثابت.
height int32

الارتفاع بالبكسل لهذا الإعلان المصاحب.
width int32

عرض هذا الإعلان المصاحب بالبكسل.
resource string

بالنسبة إلى الإعلانات المصاحبة ثابتة وiframe، سيكون هذا هو عنوان URL الذي سيتم تحميله المعروضة. بالنسبة إلى إعلانات HTML المصاحبة، سيكون هذا مقتطف HTML الذي يجب سيظهر كعنصر مصاحب
type string

نوع هذا الإعلان المصاحب. ويمكن أن يكون الرمز ثابتًا أو iframe أو HTML.
ad_slot_id string

رقم تعريف الخانة لهذا الإعلان المصاحب.
api_framework string

إطار عمل واجهة برمجة التطبيقات لهذا الإعلان المصاحب
tracking_events [object(TrackingEvent)]

قائمة أحداث التتبُّع لهذا الإعلان المصاحب.

InteractiveFile

يحتوي InteractiveFile على معلومات حول تصميم الإعلان التفاعلي (مثل SIMID) الذي يجب عرضه أثناء تشغيل الإعلان
تمثيل JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
الحقول
resource string

عنوان URL لتصميم الإعلان التفاعلي
type string

نوع MIME للملف المقدَّم كمورد.
variable_duration boolean

ما إذا كان تصميم الإعلان هذا قد يطلب تمديد المدة
ad_parameters string

قيمة <Adparams> في نموذج عرض إعلانات الفيديو (VAST)