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

تتيح لك واجهة برمجة التطبيقات Dynamic Ad Insertion API طلب وتتبّع أحداث بث الفيديو المسجّل (VOD) التي تستخدم ميزة DAI. يمكن استخدام مجموعات بث 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 على معلومات عن التحقّق المفتوح من خلال القياس لمصادر البيانات التي لا تشير إلى جهة الخادم. يحتوي 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),
}

حدث

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

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

{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": 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,
}

InteractiveFile

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