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

تتيح لك واجهة برمجة التطبيقات Dynamic Ad Insertion API طلب ومتابعة عمليات إدراج الإعلانات الديناميكية في البث المباشر للفيديوهات عند الطلب. تتوفّر مصادر البث المباشر وفق بروتوكول HTTP ‏(HLS) و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.

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

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