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

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

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

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

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

طلب 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 فقط.

فتح القياس

يحتوي الحقل Verifications على معلومات عن الدالة Open التحقّق من صحة قياس مصادر البيانات التي لا تعتمد على الإشارات من جهة الخادم يحتوي 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 إذا تم التحقق من الوسائط بنجاح وتم إرسال كل الإشعارات.
• 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 بكل إعلان طلب التحقق.

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

بث

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

الحدث

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