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

تتيح لك واجهة برمجة التطبيقات Dynamic Ad Insertion API طلب وتتبُّع عمليات بث الفيديوهات عند الطلب باستخدام DAI. يمكن البث عبر HLS وDASH.

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

يرتبط مسار طريقة stream بالمقياس https://dai.google.com.

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

الطُرق
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

إنشاء بث HLS DAI لمصدر المحتوى ومعرّف الفيديو المحدّدَين

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

إنشاء بث DASH DAI لمصدر المحتوى ومعرّف الفيديو المحدّدَين

طلب HTTP

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

عنوان الطلب

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

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

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

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

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

المعلمات
content-source string

رقم تعريف نظام إدارة المحتوى الخاص بالبث.

video-id string

معرّف الفيديو للبث.

نص الطلب

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

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

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

نص الاستجابة

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

فتح القياس

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

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

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

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

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

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

طلب HTTP

GET {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_".

ويجب إلحاق المحتوى النصي الكامل للإطار بالسمة media_verification_url لكل طلب تحقُّق من الإعلان.

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

سيتم إدراج معرّفات وسائط الإعلانات في البيان باستخدام عنصر EventStream في DASH.

سيتضمّن كل EventStream معرّف موارد منتظم (URI) لمعرّف المخطط بقيمة urn:google:dai:2018. وستشمل أحداثًا تشتمل على السمة messageData التي تحتوي على رقم تعريف وسائط إعلان يبدأ بـ “google_”. يجب إلحاق محتوى السمة messageData بالكامل بالسمة media_verification_url لكل طلب لإثبات ملكية الإعلان.

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

بث المحتوى

تُستخدَم ساحة المشاركات لعرض قائمة بجميع الموارد الخاصة بمصدر بيانات تم إنشاؤه حديثًا بتنسيق JSON .
تمثيل JSON
{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}
الحقول
stream_id string

معرّف مصدر البيانات:
total_duration number

مدة البث بالثواني.
content_duration number

مدة المحتوى، بدون إعلانات، بالثواني
valid_for string

البث المباشر مدّته صالح بالتنسيق "00h00m00s".
valid_until string

تاريخ سريان البث حتى يكون بالتنسيق RFC 3339.
subtitles [object(Subtitle)]

قائمة الترجمة: يتم حذفها إذا كانت فارغة. بروتوكول HLS فقط
hls_master_playlist string

(تم إيقاف هذا الخيار) عنوان URL لقائمة التشغيل الرئيسية في بروتوكول HLS. استخدِم Stream_manifest. بروتوكول HLS فقط
stream_manifest string

بيان ساحة المشاركات: يتطابق مع قائمة التشغيل الرئيسية في HLS وMPD في DASH. هذا هو الحقل الوحيد إلى جانب "stream_id" الموجود في الاستجابة عند إنشاء بث إشارة من جهة الخادم.
media_verification_url string

عنوان URL للتحقق من الوسائط
apple_tv object(AppleTV)

معلومات اختيارية خاصة بأجهزة AppleTV بروتوكول HLS فقط
ad_breaks [object(AdBreak)]

قائمة بالفواصل الإعلانية: يتم حذفها إذا كانت فارغة.

AppleTV

يحتوي AppleTV على معلومات خاصة بأجهزة Apple TV.
تمثيل JSON
{
  "interstitials_url": string,
}
الحقول
interstitials_url string

عنوان URL للإعلانات البينية:

AdBreak

تصف AdBreak فاصلاً إعلانيًا واحدًا في البث. وتحتوي على موضع ومدة ونوع (منتصف/قبل/نشر) وقائمة بالإعلانات.
تمثيل JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
الحقول
type string

أنواع الفواصل الصالحة هي: في منتصفها أو قبلها أو بعدها.
start number

تحديد موضع الفاصل في البث المباشر بالثواني:
duration number

مدة الفاصل الإعلاني بالثواني.
ads [object(Ad)]

قائمة بالإعلانات: يتم حذفها إذا كانت فارغة.
يصف الإعلان إعلانًا أثناء البث. وهي تشمل موضع الإعلان عند الفاصل ومدته وبعض البيانات الوصفية الاختيارية.
تمثيل JSON
{
  "seq": number,
  "start": 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,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
الحقول
seq number

موضع الإعلان في الفاصل.
start 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

عنوان URL اختياري للنقر.
icons [object(Icon)]

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

قائمة بالأغلفة. يتم حذفها إذا كانت فارغة.
events [object(Event)]

قائمة بالأحداث في الإعلان
verifications [object(Verification)]

إدخالات اختيارية لإثبات الملكية باستخدام "القياس المفتوح" تتضمّن الموارد والبيانات الوصفية المطلوبة لتنفيذ رمز القياس التابع لجهة خارجية من أجل التحقّق من تشغيل المواد الإبداعية
universal_ad_id object(UniversalAdID)

رقم تعريف الإعلان العام الاختياري.
companions [object(Companion)]

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

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

حدث

يحتوي الحدث على نوع حدث ووقت لعرضه.
تمثيل JSON
{
  "time": number,
  "type": string,
}
الحقول
time number

وقت العرض التقديمي لهذه الفعالية
type string

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

العنوان الفرعي

يصف العنوان الفرعي مسار الترجمة المصاحبة للفيديو الجانبي. وهو يخزن تنسيقين للترجمة: TTML وWebVTT. تضم سمة TTMLPath عنوان URL الخاص بملف TTML الجانبي، كما تحتوي سمة WebVTTPath على عنوان URL أيضًا على عنوان ملف WebVTT الجانبي.
تمثيل JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
الحقول
language string

رمز لغة، مثل "en" أو "de"
language_name string

الاسم الوصفي للغة: يميز المجموعة المحددة من الترجمة في حالة وجود مجموعات متعددة لنفس اللغة
ttml string

عنوان URL اختياري لملف TTML الجانبي.
webvtt string

عنوان URL اختياري لملف WebVTT الجانبي.

الرمز

يحتوي الرمز على معلومات حول رمز نموذج عرض إعلانات فيديو (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