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

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

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

ترتبط كل معرّفات الموارد المنتظمة (URI) التالية بالموقع الإلكتروني https://dai.google.com.

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

طلب HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

عنوان الطلب

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

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

نص الطلب

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

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على Stream بالنسبة إلى أحداث البث التي تقدِّم إشارات من جهة الخادم، إنّ حدث Stream هذا يحتوي على الحقلين stream_id وstream_manifest فقط.

فتح القياس

تحتوي DAI API على معلومات لإثبات صحة بيانات القياس المفتوح في Verifications. يحتوي هذا الحقل على حقل واحد أو أكثر عناصر Verification التي تسرد الموارد والبيانات الوصفية المطلوبة للتنفيذ رمز القياس التابع لجهة خارجية للتحقّق من تشغيل المواد الإبداعية. فقط يُسمح باستخدام JavaScriptResource. لمزيد من المعلومات، يُرجى الاطّلاع على مختبر IAB التقني مواصفات VAST 4.1:

الطريقة: التحقق من الوسائط

بعد العثور على معرّف لوسائط الإعلانات أثناء التشغيل، طلب باستخدام media_verification_url التي تم الحصول عليها من ساحة المشاركات نقطة نهاية أعلى. هذه الطلبات ليست ضرورية لإجراء إشارة من جهة الخادم عمليات البث، حيث يبدأ الخادم التحقق من الوسائط.

الطلبات المُرسَلة إلى نقطة النهاية media verification ثابتة.

طلب HTTP

GET https://{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_"

يجب إلحاق المحتوى النصي الكامل للإطار بعملية التحقق من الإعلان. عنوان URL قبل تقديم كل طلب من طلبات التحقق من الإعلانات.

الطريقة: البيانات الوصفية

تعرض نقطة نهاية البيانات الوصفية في metadata_url المعلومات المستخدمة لإنشاء إعلان واجهة مستخدم لا تتوفر نقطة نهاية البيانات الوصفية لعمليات البث التي تتم الإشارة من جهة الخادم إليها، يكون فيها الخادم مسؤولاً عن بدء عملية التحقّق من وسائط الإعلانات.

طلب HTTP

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

نص الاستجابة

إذا كانت الاستجابة ناجحة، فستعرض الاستجابة مثيل PodMetadata

العمل باستخدام بيانات التعريف

تتألف البيانات الوصفية من ثلاثة أقسام منفصلة: tags وads والإعلان breaks. الإدخال البيانات هي القسم tags. بعد ذلك، كرِّر العلامات وأبحث عن الإدخال الأول الذي يكون اسمه بادئة معرّف وسائط الإعلانات الذي تم العثور عليه في الفيديو المضمّن. على سبيل المثال، رقم تعريف وسائط إعلان يبدو كالتالي:

google_1234567890

بعد ذلك، ستجد عنصر علامة باسم google_12345. في هذه الحالة، يتطابق مع الرقم التعريفي للوسائط الإعلانية بعد العثور على عنصر بادئة الوسائط الإعلانية الصحيح، يمكنك البحث وأرقام تعريف الإعلانات، وأرقام تعريف الفواصل الإعلانية، ونوع الحدث. بعد ذلك، يتم استخدام الأرقام التعريفية للإعلانات لفهرسة تُستخدَم كائنات ads وأرقام تعريف الفواصل الإعلانية لفهرسة كائنات breaks.

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

بث

{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}

PodMetadata

{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}

TagSegment

{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}

AdBreak

{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}

إعلان

{
  "ad_break_id": string,
  "position": 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,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}

الرمز

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