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

تتيح لك واجهة برمجة التطبيقات "إدراج إعلان ديناميكي" طلب أحداث البث المباشر وتتبُّعها.

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

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

الطريقة: stream

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

Open Measurement

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

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

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

الطلبات إلى نقطة النهاية media verification هي طلبات متكررة.

طلب HTTP

GET https://{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 الخاص بالتحقّق من الإعلان قبل تقديم كل طلب تحقّق من الإعلان.

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

تعرض نقطة نهاية بيانات التعريف في 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)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}

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