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

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

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

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

الطريقة: stream

طلب 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

عنوان الطلب

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

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

نص الطلب

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

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على 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 هي طلبات متكررة.

طلب 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_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)],
}

AppleTV

{
  "interstitials_url": string,
}

AdBreak

{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}

إعلان

{
  "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": [],
}

الحدث

{
  "time": number,
  "type": string,
}

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

{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}

SkipMetadata

{
  "offset": number,
  "tracking_url": 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

{
  "url": string,
}

FallbackImage

{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}

Wrapper

{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}

التحقق

{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}

JavaScriptResource

{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}

TrackingEvent

{
  "event": string,
  "uri": string,
}

UniversalAdID

{
  "id_value": string,
  "id_registry": string,
}

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

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

InteractiveFile

{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}