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

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

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

تتيح لك واجهة برمجة التطبيقات Dynamic Ad Insertion API طلب ميزة "إدراج إعلان ديناميكي" وتتبُّعها عمليات بث الفيديوهات المتوفرة عند الطلب يمكن البث عبر 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 لمصدر المحتوى ومعرّف الفيديو المحدّدَين

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>"

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 على معلومات عن الدالة Open التحقّق من صحة قياس مصادر البيانات التي لا تعتمد على الإشارات من جهة الخادم يحتوي 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)], }

تمثيل 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), "skip_metadata": object(SkipMetadata), }

{
  "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),
}

الحقول
`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) الذي يجب عرضه أثناء تشغيل الإعلان
`skip_metadata`	`object(SkipMetadata)` البيانات الوصفية الاختيارية للإعلانات القابلة للتخطّي: في حال ضبطها، يشير ذلك إلى أن الإعلان قابل للتخطي ويتضمن تعليمات حول كيفية التعامل مع واجهة مستخدم التخطي وتتبُّع الأحداث

الحدث

يحتوي الحدث على نوع حدث ووقت لعرضه.

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

توفّر StepMetadata المعلومات اللازمة للعملاء للتعامل مع أحداث التخطي للإعلانات القابلة للتخطي.

تمثيل JSON
{ "offset": number, "tracking_url": string, }

الحقول
`offset`	`number` تشير الإزاحة إلى مقدار الوقت المستغرَق بالثواني في عرض الإعلان. يجب الانتظار حتى يتم عرض زر التخطي. ويتم حذفها إذا لم يتم توفيرها في نموذج عرض إعلانات فيديو (VAST).
`tracking_url`	`string` يحتوي عنوان URL للتتبّع على عنوان 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

يحتوي برنامج الغلاف على معلومات عن إعلان برنامج تضمين. لا يتضمّن رقم تعريف الصفقة إذا لم يكن متوفّرًا.

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

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