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

تتيح لك واجهة برمجة التطبيقات الخاصة بميزة "إدراج الإعلان الديناميكي" طلب وتتبُّع بث الفيديوهات عند الطلب (VOD) التي تستخدم ميزة "إدراج الإعلان الديناميكي". يمكن استخدام بث مباشر وفق بروتوكول HTTP ‏(HLS) وبروتوكول البث التكيّفي الديناميكي عبر HTTP ‏(DASH).

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

يكون مسار الطريقة stream نسبيًا إلى https://dai.google.com

الطريقة: stream

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

ينشئ هذا الإجراء بثًا باستخدام ميزة "إدخال الإعلانات الديناميكي" في HLS لمصدر المحتوى ومعرّف الفيديو المحدّدَين.

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

تنشئ هذه الطريقة بثًا باستخدام ميزة "إدخال الإعلانات الديناميكي" في DASH لمصدر المحتوى ومعرّف الفيديو المحدّدَين.

طلب 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. يتم بدء عملية التتبُّع في مصدر البيانات التلقائي من جهة العميل، ويتم إرسال إشارة ping من جهة الخادم.
مَعلمات الاستهداف في "برنامج ناشري DoubleClick" اختياري مَعلمات الاستهداف الإضافية
تجاوز مَعلمات البث اختياري تجاوز القيم التلقائية لمَعلمة إنشاء بث
مصادقة HMAC اختياري المصادقة باستخدام رمز مميّز يستند إلى HMAC

نص الاستجابة

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

Open Measurement

يحتوي الحقل Verifications على معلومات للتحقّق من Open Measurement في عمليات البث التي لا تستخدم إشارات من جهة الخادم. يحتوي 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 إذا نجحت عملية التحقّق من صحة الوسائط وتم إرسال جميع طلبات Ping
  • ‫HTTP/1.1 404 Not Found إذا تعذّر على الطلب التحقّق من الوسائط بسبب تنسيق عنوان URL غير صحيح أو انتهاء صلاحيته
  • HTTP/1.1 404 Not Found إذا نجح طلب سابق لإثبات الهوية باستخدام مستند التعريف هذا
  • HTTP/1.1 409 Conflict إذا كان طلب آخر يرسل إشارات ping في هذا الوقت

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

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

يجب إلحاق كل محتوى النص في الإطار بعنوان URL الخاص بـ media_verification_url لكل طلب تحقّق من الإعلان.

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

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

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

بيانات الردّ

بث

يتم استخدام Stream لعرض قائمة بجميع الموارد لحدث بث مباشر تم إنشاؤه حديثًا بتنسيق 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

أنواع الفواصل الصالحة هي: mid وpre وpost.
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),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}
الحقول
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)]

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

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

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

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

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

قائمة اختيارية بجميع عقد <Extension> في VAST.

الحدث

يحتوي الحدث على نوع حدث ووقت عرض الحدث.
تمثيل 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

رمز اللغة، مثل "ar" أو "de".
language_name string

اسم وصفي للغة يفرّق هذا العنصر بين مجموعات الترجمة والشرح إذا كانت هناك مجموعات متعددة للغة نفسها
ttml string

عنوان URL اختياري لملف TTML المرافق
webvtt string

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

SkipMetadata

توفّر SkipMetadata المعلومات اللازمة للعملاء للتعامل مع أحداث التخطّي للإعلانات القابلة للتخطّي.
تمثيل JSON
{
  "offset": number,
  "tracking_url": string,
}
الحقول
offset number

يشير الإزاحة إلى مقدار الوقت بالثواني الذي يجب أن ينتظره المشغّل قبل عرض زر التخطّي. يتم حذف هذا العنصر إذا لم يتم توفيره في VAST.
tracking_url string

يحتوي TrackingURL على عنوان URL يجب إرسال إشارة إليه عند وقوع حدث التخطّي.

رمز

يحتوي الرمز على معلومات حول رمز 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

رقم تعريف الصفقة الاختياري للإعلان المغلّف

التحقق

تحتوي عملية التحقّق على معلومات حول Open Measurement، ما يسهّل قياس مدى إمكانية رؤية الإعلانات والتحقّق منها من قِبل جهات خارجية. في الوقت الحالي، لا تتوفّر سوى موارد 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

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

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

يحتوي العنصر Companion على معلومات عن الإعلانات المصاحبة التي يمكن عرضها مع الإعلان.
تمثيل 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

قيمة عقدة <AdParameters> في VAST