إنّ واجهة برمجة تطبيقات DAI في مرحلة تجريبية وقد لا تكون متاحة في شبكتك. اتصل بمدير حسابك للحصول على مزيد من المعلومات. ويُنصَح باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية للأنظمة الأساسية التي تتوفّر فيها.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

تتيح لك واجهة برمجة التطبيقات Dynamic Ad Insertion API طلب ومتابعة عمليات إدراج الإعلانات الديناميكية في البث المباشر للفيديوهات عند الطلب. تتوفّر مصادر البث المباشر وفق بروتوكول HTTP ‏(HLS) وDASH.

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

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

الطريقة: stream

الطُرق

الطُرق
`stream`	`POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream` لإنشاء بث مباشر عبر بروتوكول HTTP (HLS) باستخدام ميزة DAI لمصدر المحتوى ورقم تعريف الفيديو المحدّدَين `POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream` لإنشاء بث DASH DAI لمصدر المحتوى ورقم تعريف الفيديو المحدّدَين

stream

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

لإنشاء بث مباشر عبر بروتوكول HTTP (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 بالشكل التالي: Authorization: DCLKDAI key="<api-key>"

api‑key

string

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

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

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

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

المعلمات
`content-source`	`string` رقم تعريف نظام إدارة المحتوى لمصدر البيانات
`video-id`	`string` معرّف الفيديو الخاص بالبث

نص الطلب

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

المعلمات
`dai-ssb`	اختياري	اضبط القيمة على `true` لإنشاء بث إشارات من جهة الخادم. الإعداد التلقائي هو `false`. يبدأ العميل عملية تتبُّع البث التلقائي ويُرسِل طلبًا للتحقق من صحة الاتصال من جهة الخادم.
مَعلمات استهداف DFP	اختياري	مَعلمات الاستهداف الإضافية:
إلغاء مَعلمات البث	اختياري	إلغاء القيم التلقائية لمَعلمة إنشاء البث
مصادقة HMAC	اختياري	المصادقة باستخدام رمز مميّز يستند إلى HMAC

نص الاستجابة

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

القياس المفتوح

يحتوي الحقل Verifications على معلومات لإثبات ملكية Open Measurement لملفات البث التي لا تستخدم إشارات من جانب الخادم. يحتوي Verifications على عنصر Verification واحد أو أكثر يسرد الموارد والبيانات الوصفية التي تحتاج إليها للتحقّق من تشغيل تصميم الإعلان باستخدام رمز قياس تابع لجهة خارجية. يُسمح فقط بالقيمة JavaScriptResource. لمزيد من المعلومات، يُرجى الاطّلاع على المختبَر التقني لمكتب الإعلانات التفاعلية (IAB Tech Lab) ومواصفات 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 بعنوان URL 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)], }

تمثيل 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,
  "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)]` قائمة بعناصر Wrapper يتم حذفها إذا كانت فارغة.
`events`	`[object(Event)]` قائمة بالأحداث في الإعلان
`verifications`	`[object(Verification)]` إدخالات التحقّق من القياس المفتوح الاختيارية التي تسرد الموارد والبيانات الوصفية المطلوبة لتنفيذ رمز القياس التابع لجهة خارجية للتحقّق من تشغيل تصميم الإعلان
`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` رمز اللغة، مثل en أو 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, }

تمثيل 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

يحتوي العنصر 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` معرّف الصفقة الاختياري للإعلان المُغلف

التحقّق

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

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

يحتوي القسم "مصاحب" على معلومات عن الإعلانات المصاحبة التي قد يتم عرضها مع الإعلان.

تمثيل 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)], }

تمثيل 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 إذا كان هذا إعلانًا مصاحبًا من النوع static
`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