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

تمكّنك واجهة برمجة تطبيقات إدراج الإعلان الديناميكي من طلب مجموعات بث DAI (مباشر) وتتبعها.

الخدمة: 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 على معلومات حول التحقق من القياس المفتوح في الحقل 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 في حال نجاح التحقُّق من الوسائط وإرسال جميع الإشعارات.
• 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

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

البيانات الوصفية لـ Pod

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

شريحة العلامة

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

بيانات النقر

{
  "url": string,
}

صورة احتياطية

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

حدث التتبع

{
  "event": string,
  "uri": string,
}

معرّف الإعلانات العام

{
  "id_value": string,
  "id_registry": string,
}

الإعلان المصاحب

{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
}

ملف تفاعلي

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