واجهة برمجة التطبيقات المباشرة التي تعرض لوحة "إدراج إعلان ديناميكي"

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

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

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

الطريقة: stream

الطُرق
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

تسجيل مجموعة DAI DAI لعرض جلسة بث مباشر

طلب HTTP

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

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

المعلمات
network_code string

رمز شبكة "مدير إعلانات Google" الخاص بالناشر

custom_asset_key string

المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google".

نص الطلب

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

المعلمات
مَعلمات استهداف DFP اختياري مَعلمات الاستهداف الإضافية:
إلغاء مَعلمات البث اختياري إلغاء القيم التلقائية لمَعلمة إنشاء البث
مصادقة HMAC اختياري المصادقة باستخدام رمز مميّز يستند إلى HMAC

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على عنصر Stream جديد.

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

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

الطريقة: قسم الحزمة

الطُرق
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}

لإنشاء مصدر بيانات متوفّر أثناء التشغيل (DAI) لرقم تعريف الحدث المحدّد

طلب HTTP

GET https://dai.google.com/linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}

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

المعلمات
network_code string

رمز شبكة "مدير إعلانات Google" الخاص بالناشر

custom_asset_key string

المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google".

pod_identifier

تتوفّر التنسيقات التالية:

pod/{integer}

المعرّف الرقمي للفاصل الإعلاني الحالي. يتم تحديد معرّفات مجموعات الإعلانات بشكل تدريجي لكلّ حدث فاصل إعلاني، بدءًا من 1.

ad_break_id/{string}

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

profile_name string

اسم ملف ترميز DAI في "مدير إعلانات Google" المطلوب يجب أن يكون ملفّ تعريف الترميز أحد ملفات تعريف الترميز التي تمّ إعدادها للحدث المحدّد.

segment_number integer

فهرس الشريحة المطلوبة ضمن مجموعة الإعلانات المتسلسلة الحالية، بدءًا من الصفر
segment_format string

إضافة الملف المرتبطة بتنسيق المقطع المطلوب الإضافات المقبولة هي: ts أو mp4 أو vtt أو aac أو ac3 أو eac3.

مَعلمات طلب البحث

المعلمات
stream_id مطلوبة string

رقم تعريف مصدر البيانات لجلسة المستخدِم الحالية. يتم عرض هذه القيمة من قِبل طلب ناجح إلى نقطة نهاية stream.
sd required1 integer

مدة المقطع المطلوب، بالمللي ثانية
so اختيارية

بدء المقطع المطلوب ضمن مجموعة الإعلانات المتسلسلة، بالمللي ثانية في حال حذف المَعلمة so، سيتم احتسابها من خلال ضرب مدة المقطع بعدد الشرائح.
pd سمة مطلوبة2 integer

مدة مجموعة الإعلانات المتسلسلة، بالمللي ثانية
auth-token مطلوبة string

رمز HMAC الموقَّع والمترميز بنظام عناوين URL للمجموعة الإعلانية الحالية
last اختيارية boolean

يشير إلى المقطع الأخير في الفاصل الإعلاني. واصِل حذف هذه المَعلمة من كل الشرائح الأخرى.
scte35 اختيارية string

إشارة SCTE-35 بترميز Base64 لهذا الفاصل الإعلاني
cust_params اختيارية string

مجموعة من أزواج المفاتيح والقِيم، تُستخدَم لاستهداف الحملات في "مدير الحملة". يجب تمثيل هذه الثنائيات على شكل سلسلة طلب بحث مُشفَّرة بتنسيق عنوان URL.

مثال:
المعلمات
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

الحواشي السفلية

  1. sd غير مطلوب لمقاطع الإعداد. ↩
  2. لا يلزم استخدام pd للأحداث التي تم فيها تفعيل ميزة فسلات الإعلانات التي لا تملك مدة. ↩

مثال

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيكون نص الاستجابة عبارة عن مقطع بث قابل للتشغيل يتطابق مع التنسيق والمَعلمات المحدّدة في الطلب.

الطريقة: بيان مجموعة HLS

يسترجع بيان مجموعة الإعلانات في مجموعة HLS لبث مباشر جاهز لمشغّل فيديو العميل لتحميله وتشغيله.

الطُرق
GET GET /linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset}/{pod_identifier}.m3u8;

واجهة برمجة تطبيقات لاسترداد قائمة تشغيل متعددة الصيغ بتنسيق HLS لمجموعة إعلانية.

طلب HTTP

GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}.m3u8?stream_id={stream_id}&pd={pod_duration}

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

المعلمات
network_code string

رمز شبكة "مدير إعلانات Google" الخاص بالناشر
custom_asset_key string

المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google"
pod_identifier

تتوفّر التنسيقات التالية:

pod/{integer}

المعرّف الرقمي للفاصل الإعلاني الحالي. يتم تحديد معرّفات مجموعات الإعلانات بشكل تدريجي لكلّ حدث فاصل إعلاني، بدءًا من 1.

ad_break_id/{string}

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

مَعلمات طلب البحث

المعلمات
stream_id مطلوب string

رقم تعريف مصدر البيانات لجلسة المستخدِم الحالية. يتم عرض هذه القيمة من خلال طلب ناجح إلى نقطة نهاية stream.
pd مطلوب integer

مدة مجموعة الإعلانات المتسلسلة، بالمللي ثانية
scte35 اختيارية string

إشارة SCTE-35 بترميز Base64 لهذا الفاصل الإعلاني
cust_params اختيارية string

مجموعة من أزواج المفاتيح والقِيم، تُستخدَم لاستهداف الحملات في "مدير الحملة". يجب تمثيل هذه الثنائيات على شكل سلسلة طلب بحث مُشفَّرة بتنسيق عنوان URL.

مثال:
المعلمات
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

نص الاستجابة

إذا كانت الاستجابة ناجحة، يكون نص الاستجابة عبارة عن قائمة تشغيل متعددة الصيغ بتنسيق HLS.

الطريقة: بيان مجموعة DASH

يسترجع بيان مجموعة الإعلانات MPEG-DASH لبث مباشر جاهز لتحميله وتشغيله من قِبل مشغّل فيديو العميل.

الطُرق
GET GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/pod/{pod_id}/manifest.mpd

واجهة برمجة تطبيقات لاسترداد قائمة تشغيل mpd بتنسيق MPEG-DASH لمجموعة إعلانية

طلب HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}

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

المعلمات
network_code string

رمز شبكة "مدير إعلانات Google" الخاص بالناشر
custom_asset_key string

المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google"
stream_id string

رقم تعريف مصدر البيانات لجلسة المستخدِم الحالية. يتم عرض هذه القيمة من خلال طلب ناجح إلى نقطة نهاية stream.
pod_id integer

المعرّف الرقمي للفاصل الإعلاني الحالي. يتم تحديد معرّفات مجموعات الإعلانات بشكل تدريجي لكلّ حدث فاصل إعلاني، بدءًا من 1.

مَعلمات طلب البحث

المعلمات
pd مطلوب integer

مدة مجموعة الإعلانات المتسلسلة، بالمللي ثانية
scte35 اختيارية string

إشارة SCTE-35 بترميز Base64 لهذا الفاصل الإعلاني
cust_params اختيارية string

مجموعة من أزواج المفاتيح والقِيم، تُستخدَم لاستهداف الحملات في "مدير الحملة". يجب تمثيل هذه الثنائيات على شكل سلسلة طلب بحث مُشفَّرة بتنسيق عنوان URL.

مثال:
المعلمات
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

نص الاستجابة

إذا كانت الاستجابة ناجحة، يكون نص الاستجابة عبارة عن قائمة تشغيل mpd بتنسيق MPEG-DASH.

الطريقة: نموذج فترة مجموعة DASH

الطُرق
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

يطلب نموذج فترة DASH من "مدير إعلانات Google". يحتوي هذا النموذج على وحدات ماكرو يجب تعبئتها بمَعلمات البث. بعد تعبئة هذه الوحدات النمطية، يصبح النموذج هو مدة الفاصل الإعلاني، ويمكن دمجه في بيان DASH.

طلب HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

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

المعلمات
network_code string

رمز شبكة "مدير إعلانات Google" الخاص بالناشر

custom_asset_key string

المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google".

مَعلمات طلب البحث

المعلمات
stream_id مطلوبة string

رقم تعريف مصدر البيانات لجلسة المستخدِم الحالية. يتم عرض هذه القيمة من قِبل طلب ناجح إلى نقطة نهاية stream.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على عنصر PodTemplateResponse جديد.

الطريقة: البيانات الوصفية لتوقيت مجموعة الإعلانات

الطُرق
ad pod timing metadata GET /linear/pods/v1/adv/network/{network_code}/custom_asset/{custom_asset_key}/pod.json

يسترجع البيانات الوصفية لتوقيت مجموعة الإعلانات.

طلب HTTP

GET https://dai.google.com/linear/pods/v1/adv/network/{network_code}/custom_asset/{custom_asset_key}/pod.json

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

المعلمات
network_code string

رمز شبكة "مدير إعلانات Google" الخاص بالناشر

custom_asset_key string

المعرّف المخصّص المرتبط بهذا البث المباشر في "مدير إعلانات Google"

مَعلمات طلب البحث

المعلمات
stream_id مطلوب string

رقم تعريف البث في "مدير الإعلانات" من تطبيق مشغّل الفيديو للعملاء
ad_break_id مطلوبة string

رقم تعريف الفاصل الإعلاني التالي القادم.

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

تنطبق القيود التالية على أرقام تعريف الفواصل الإعلانية المخصّصة:

  • يجب أن يتألّف من بين حرف واحد و63 حرفًا
  • يجب أن يحتوي على أحرف لاتينية صغيرة وأرقام وواصلات فقط.
  • تم حجز رقم تعريف الفاصل الإعلاني preroll لاسترداد مجموعة الإعلانات المتسلسلة التي تظهر قبل التشغيل. ولا يمكن استخدامه لتحديد أي مجموعة أخرى من الإعلانات.
auth-token مطلوبة string

يتم إنشاء auth-token بالطريقة نفسها التي يتم بها إنشاء الرمز المميّز لبروتوكول HMAC في سير عمل عرض مجموعات التطبيقات الأساسية، ولكن يتم إنشاؤه من المَعلمات التالية:

  • ad_break_id
  • custom_asset_key
  • exp
  • network_code
  • custom_params
  • pd
  • scte35
timeout اختيارية integer

عدد المللي ثانية الذي يمكن أن تحظر فيه ميزة DAI هذا الطلب في انتظار اتخاذ قرار بشأن الإعلان. استخدِم هذه المَعلمة في الطلبات التي يجب أن تعرِض إعلانات مملوءة في الطلب الأول، مثل الفواصل الإعلانية قبل التشغيل.

في حال تجاوز المهلة، يعرض الطلب حالة "في انتظار المراجعة".

في حال تضمينها، يجب أن تتراوح قيمة المهلة بين 1,000 و15,000 ملي ثانية. وفي حال حذفها، لا يتم تأخير الردود في انتظار اتخاذ قرارات بشأن الإعلانات.
final اختيارية boolean

اضبط القيمة على true للإشارة إلى ميزة "العرض الإعلاني الديناميكي" بأنّ هذا هو الطلب الأخير الذي يريده "مزوّد خدمة عرض الفيديو" لتقديمه لهذه المجموعة الإعلانية. إذا لم يكن قرار الإعلان متاحًا بعد (باستخدام مهلة اختيارية)، ستُعرِض ميزة DAI لوحة إعلانات بشكل دائم لهذا الطلب.

الإعداد التلقائي هو false.

مَعلمات اتّخاذ القرار بشأن الإعلانات
pd اختيارية integer

مدة الفاصل الإعلاني (بالمللي ثانية) يُشار إليها أيضًا باسم مدّة مجموعات الإعلانات المتسلسلة.

في حال استخدام EABN، يجب أن تتطابق قيمة pd مع المدة المقدَّمة في إشعار الفاصل الإعلاني. إذا لم تتطابق المدّتان، سيتم منح القيمة EABN الأولوية.

cust_params اختيارية string

المَعلمات المخصّصة لاستهداف الفواصل الإعلانية، كما هو موضّح في مركز مساعدة "مدير الإعلانات"
scte35 اختيارية string

إشارة SCTE-35 مُشفَّرة باستخدام Base64

إذا كانت الإشارة غير صالحة، سيتم إرسال رسالة في رأس HTTP‏ X-Ad-Manager-Dai-Warning للاستجابة وسيتم إرسال الطلب بدون قيمة scte35 غير الصالحة.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على عنصر AdPodTimingMetadataResponse جديد.

الطريقة: إثبات ملكية الوسائط

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

تكون الطلبات المرسَلة إلى نقطة النهاية media verification أحادية المفعول.

الطُرق
media verification GET /{media_verification_url}/{ad_media_id}

إرسال إشعار إلى واجهة برمجة التطبيقات بحدث إثبات ملكية الوسائط

طلب 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 أو رسالة emsg لملفات mp4. ستبدأ معرّفات وسائط الإعلانات دائمًا بسلسلة google_.

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

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

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

الطُرق
metadata GET /{metadata_url}/{ad-media-id}

GET /{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.

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

بث

يتم استخدام بث لعرض قائمة بالموارد لبث تم إنشاؤه حديثًا بتنسيق JSON.
تمثيل JSON
{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
الحقول
stream_id string

معرّف مصدر البيانات في "مدير إعلانات Google"
media_verification_url string

عنوان URL لإثبات ملكية الوسائط المستخدَم كنقطة نهاية أساسية لتتبُّع أحداث التشغيل
metadata_url string

عنوان URL للبيانات الوصفية المستخدَم للاستعلام عن معلومات دورية حول أحداث الإعلانات القادمة في أحداث البث
session_update_url string

عنوان URL لتعديل الجلسة المستخدَم لتعديل مَعلمات الاستهداف لهذا البث. يتم تسجيل القيم الأصلية لمَعلمات الاستهداف أثناء طلب إنشاء البث الأوّلي.
heartbeat_url string

عنوان URL الخاص برسائل التحقّق، والذي يُستخدَم للحفاظ على استمرار بث إشارات الالتقاط من جهة الخادم، يجب إرسال رسائل التحقّق إليه كل {PollingFrequency} ثانية. يتمّ تعبئتها لملفات البث من جهة الخادم التي تتضمّن إشارات.
polling_frequency number

وتيرة الاستطلاع، بالثواني، عند طلب metadata_url أو heartbeat_url
pod_manifest_url string

يُستخدَم نموذج عنوان URL لبيان مجموعة البث لإنشاء عنوان URL لاسترداد بيان مجموعة البث الخاص بالبث، وهو يتوافق مع عنوان URL لقائمة التشغيل المتعدّدة الصيغ في HLS أو ملف MPD في DASH. يتمّ تعبئته لأحداث البث المباشر من نوع "إدراج إعلان ديناميكي" POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

تنسيق البيان هو تنسيق البيان الذي تم استرجاعه من pod_manifest_url، سواء كان dash أو hls.

PodMetadata

يحتوي PodMetadata على معلومات البيانات الوصفية عن الإعلانات والفواصل الإعلانية وعلامات معرّفات الوسائط.
تمثيل JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
الحقول
tags map[string, object(TagSegment)]

خريطة لأجزاء العلامات المفهرَسة حسب بادئة العلامة
ads map[string, object(Ad)]

خريطة الإعلانات المفهرَسة حسب رقم تعريف الإعلان
ad_breaks map[string, object(AdBreak)]

خريطة الفواصل الإعلانية التي تمّت فهرستها حسب معرّف الفاصل الإعلاني

TagSegment

يحتوي TagSegment على إشارة إلى إعلان وفاصل إعلاني ونوع الحدث. يجب عدم إرسال طلب بحث إلى TagSegment التي يكون فيها type="progress" إلى نقطة نهاية التحقّق من ملفّات وسائط الإعلان.
تمثيل JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
الحقول
ad string

معرّف إعلان هذه العلامة.
ad_break_id string

رقم تعريف الفاصل الإعلاني لهذه العلامة.
type string

نوع الحدث لهذه العلامة

AdBreak

يصف AdBreak فاصل إعلاني واحد في البث. يحتوي على مدة، ونوع (أثناء/قبل/بعد) وعدد الإعلانات.
تمثيل JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
الحقول
type string

أنواع الفواصل الصالحة هي: ما قبل البث وما بين البث وما بعد البث.
duration number

إجمالي مدة الإعلانات لهذا الفاصل الإعلاني، بالثواني
expected_duration number

المدة المتوقّعة للفاصل الإعلاني (بالثواني)، بما في ذلك جميع الإعلانات وأي لوحة إعلانية.
ads number

عدد الإعلانات في الفاصل الإعلاني
يصف العمود "الإعلان" إعلانًا في البث.
تمثيل JSON
{
  "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),
}
الحقول
ad_break_id string

رقم تعريف الفاصل الإعلاني لهذا الإعلان.
position number

موضع هذا الإعلان في الفاصل الإعلاني، بدءًا من 1
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

عنوان URL اختياري للنقرة.
click_tracking_urls string

عناوين URL اختيارية لتتبُّع النقرات:
verifications [object(Verification)]

إدخالات التحقّق من القياس المفتوح الاختيارية التي تسرد الموارد والبيانات الوصفية المطلوبة لتنفيذ رمز القياس التابع لجهة خارجية للتحقّق من تشغيل تصميم الإعلان
slate boolean

قيمة منطقية اختيارية تشير إلى أنّ الإدخال الحالي هو لوحة معلومات.
icons [object(Icon)]

قائمة الرموز، يتم حذفها إذا كانت فارغة.
wrappers [object(Wrapper)]

قائمة بعناصر Wrappers، يتم حذفها إذا كانت فارغة
universal_ad_id object(UniversalAdID)

معرّف إعلان عالمي اختياري:
extensions string

قائمة اختيارية لجميع عقد <Extension> في ملف VAST
companions [object(Companion)]

الإعلانات المصاحبة الاختيارية التي قد تظهر مع هذا الإعلان
interactive_file object(InteractiveFile)

تصميم إعلان تفاعلي اختياري (SIMID) يجب عرضه أثناء تشغيل الإعلان

PodTemplateResponse

يمثّل PodTemplateResponse الحمولة في تنسيق JSON التي يتم إرجاعها إلى VTP لدمج الحِزم.
تمثيل JSON
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
الحقول
dash_period_template string

DashPeriodTemplate هو نموذج xml للفترة التي سيتم ملؤها بالبيانات المناسبة قبل التجميع.
segment_duration_ms int64

SegmentDurationMS هي مدة شرائح الفترة بالمللي ثانية.

AdpodTimingMetadataResponse

يحتوي AdpodTimingMetadataResponse على معلومات عن مجموعة الإعلانات وكيفية إنشاء عناوين URL للشرائح لها.
تمثيل JSON
{
  "status": string,
  "ads": [object(AdRendering)],
  "slate": object(SlateRendering),
  "dash_representations": map[string, object(DASHRepresentation)],
  "dash_adaptation_sets": map[string, object(DASHAdaptationSet)],
}
الحقول
status string

حالة القرار المتعلّقة بمجموعة الإعلانات المتسلسلة.
ads [object(AdRendering)]

صفيف عناصر الإعلانات التي تصف كيفية عرض عناوين URL لشرائح الإعلانات، مفهرَسة بدءًا من 0
slate object(SlateRendering)

لوحة وصفية توضّح كيفية عرض عناوين URL لشرائح لوحة العرض
dash_representations map[string, object(DASHRepresentation)]

قائمة بتمثيلات DASH لمجموعة الإعلانات هذه التي سيتم عرضها في ملفات بيان DASH
dash_adaptation_sets map[string, object(DASHAdaptationSet)]

قائمة مجموعات DASH Adaptation لعرض مجموعة الإعلانات هذه في ملفات بيان DASH

AdRendering

يوضّح AdRendering كيفية عرض إعلان تمّ اتخاذ قرار بشأنه.
تمثيل JSON
{
  "duration_ms": number,
  "variants": map[string, object(VariantRendering)],
}
الحقول
duration_ms number

مدة الإعلان، بالمللي ثانية (int).
variants map[string, object(VariantRendering)]

قاموس عناصر الأسعار المتغيرة (راجِع المعلومات أدناه)، مفهرَسًا حسب رقم تعريف السعر المتغير/الملف الشخصي، كما تم ضبطه من واجهة المستخدم

SlateRendering

يصف SlateRendering كيفية عرض محتوى لوحة المعلومات.
تمثيل JSON
{
  "duration_ms": number,
  "variants": map[string, object(VariantRendering)],
}
الحقول
duration_ms number

مدّة لوحة البيانات، بالمللي ثانية (int).
variants map[string, object(VariantRendering)]

معجم لكائنات "خيار المنتج"، مفهرَس حسب معرّف خيار المنتج/الملف الشخصي يجب تكرار مدد لوحة البيانات إلى أن يتم الوصول إلى المدة المطلوبة، أو إدراج فواصل HLS بين التكرارات، أو تكرار فترات جديدة لتنسيق MPEG-DASH.

VariantRendering

يصف VariantRendering خيارًا/ملفًا شخصيًا واحدًا ضمن الإعلان/قائمة الإعلانات.
تمثيل JSON
{
  "segment_extension": string,
  "segment_durations": object(SegmentDurations),
}
الحقول
segment_extension string

سلسلة، أحد الخيارات التالية: ts أو mp4 أو aac أو ac3 أو ec3 أو m4a أو m4v. جزء إضافة اسم الملف من عناوين URL للشرائح
segment_durations object(SegmentDurations)

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

SegmentDurations

تصف SegmentDurations مدة تسلسل الشرائح، بوحدة زمنية محدّدة.
تمثيل JSON
{
  "timescale": number,
  "values": [],
}
الحقول
timescale number

مقياس الوقت هو عدد الوحدات في الثانية (int). من المتوقّع أن يكون: 1000 لتنسيق HLS (بالملي ثانية) 90000 لفيديو DASH (PTS) معدل أخذ العينات الصوتية لصوت DASH.
values number

صفيف مدد الشرائح بالتنسيق int، بوحدات مقياس الوقت

DASHRepresentation

يصف عنصر DASHRepresentation عقد تمثيل المحتوى التي سيتم عرضها في ملفات بيان DASH.
تمثيل JSON
{
  "codecs": string,
  "bandwidth": number,
  "width": number,
  "height": number,
  "frame_rate": string,
  "audio_sampling_rate": number,
  "audio_channel_config": object(SchemeIDURIAndValue),
}
الحقول
codecs string

برامج ترميز التمثيل
bandwidth number

النطاق الترددي للتمثيل
width number

عرض التمثيل.
height number

ارتفاع التمثيل.
frame_rate string

عدد اللقطات في الثانية للعرض
audio_sampling_rate number

معدّل عينات الصوت للتمثيل
audio_channel_config object(SchemeIDURIAndValue)

إعدادات قناة الصوت للتمثيل

DASHAdaptationSet

يصف عنصر DASHAdaptationSet عقد AdaptationSet التي سيتم عرضها في بيانات DASH.
تمثيل JSON
{
  "content_type": string,
  "mime_type": string,
  "role": object(SchemeIDURIAndValue),
  "inband_event_stream": object(SchemeIDURIAndValue),
  "min_frame_rate": string,
  "max_frame_rate": string,
  "scan_type": string,
  "start_with_sap": string,
  "segment_alignment": boolean,
  "representations": [],
}
الحقول
content_type string

نوع محتوى مجموعة التحويل
mime_type string

نوع MIME لمجموعة التحويل
role object(SchemeIDURIAndValue)

دور مجموعة التحويل
inband_event_stream object(SchemeIDURIAndValue)

بث أحداث ضمن النطاق لمجموعة التحويل
min_frame_rate string

الحد الأدنى لعدد اللقطات في الثانية لمجموعة التحويل
max_frame_rate string

الحد الأقصى لعدد اللقطات في الثانية لمجموعة التحويل
scan_type string

نوع المسح لمجموعة التحويل
start_with_sap string

ابدأ بإعداد SAP لمجموعة التحويل.
segment_alignment boolean

محاذاة الشريحة لمجموعة التوافق
representations string

ممثّلات لمجموعة التحويل

SchemeIDURIAndValue

SchemeIDURIAndValue هو زوج من رقم تعريف المخطّط وقيمته.
تمثيل JSON
{
  "scheme_id_uri": string,
  "value": string,
}
الحقول
scheme_id_uri string

معرّف الموارد المنتظم (URI) لرقم تعريف المخطّط للقيمة
value string

قيمة معرّف الموارد المنتظم (URI) لنظام المخطّط

الرمز

يحتوي الرمز على معلومات عن رمز VAST.
تمثيل JSON
{
  "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,
}
الحقول
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

يحتوي العمود ClickData على معلومات عن النقر على رمز.
تمثيل JSON
{
  "url": string,
}
الحقول
url string

FallbackImage

يحتوي عنصر FallbackImage على معلومات عن صورة احتياطية لتنسيق VAST.
تمثيل JSON
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
الحقول
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

يحتوي العنصر Wrapper على معلومات عن إعلان ملفّ تعريف. ولا يتضمّن ملف السجلّ رقم تعريف الصفقة إذا لم يكن متوفّرًا.
تمثيل JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
الحقول
system string

معرّف نظام الإعلانات:
ad_id string

رقم تعريف الإعلان المستخدَم للإعلان المُغلف
creative_id string

رقم تعريف تصميم الإعلان المستخدَم للإعلان المُغلف
creative_ad_id string

رقم تعريف الإعلان المرتبط بتصميم الإعلان المستخدَم للإعلان المُغلف
deal_id string

معرّف الصفقة الاختياري للإعلان المُغلف

التحقّق

يحتوي القسم "التحقّق" على معلومات عن "القياس المفتوح"، ما يسهّل measuring إمكانية العرض والتحقق من المعلنين التابعين لجهات خارجية. في الوقت الحالي، تتوفّر فقط موارد JavaScript. يُرجى الاطّلاع على https://iabtechlab.com/standards/open-measurement-sdk/.
تمثيل JSON
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
الحقول
vendor string

مورّد عملية إثبات الهوية
java_script_resources [object(JavaScriptResource)]

قائمة بموارد JavaScript للتحقّق من المعلِنين
tracking_events [object(TrackingEvent)]

قائمة بأحداث التتبّع لإثبات الملكية
parameters string

سلسلة غير شفافة تم تمريرها إلى رمز التحقّق من عملية الإعداد

JavaScriptResource

يحتوي JavaScriptResource على معلومات للتحقّق من خلال JavaScript.
تمثيل JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
الحقول
script_url string

عنوان URI إلى الحمولة البرمجية لـ JavaScript
api_framework string

APIFramework هو اسم إطار عمل الفيديو الذي يستخدم رمز التحقّق.
browser_optional boolean

ما إذا كان يمكن تشغيل هذا النص البرمجي خارج المتصفّح

TrackingEvent

يحتوي TrackingEvent على عناوين URL التي يجب أن يرسل العميل طلبًا للاتصال بها في حالات معيّنة.
تمثيل JSON
{
  "event": string,
  "uri": string,
}
الحقول
event string

نوع حدث التتبّع:
uri string

حدث التتبُّع الذي سيتم إرسال إشعار إليه.

UniversalAdID

تُستخدَم UniversalAdID لتقديم معرّف فريد لتصميم الإعلان يتمّ الاحتفاظ به في جميع أنظمة الإعلانات.
تمثيل JSON
{
  "id_value": string,
  "id_registry": string,
}
الحقول
id_value string

رقم تعريف الإعلان العام لتصميم الإعلان المحدّد للإعلان.
id_registry string

سلسلة تُستخدَم لتحديد عنوان URL لموقع الويب الخاص بالسجلّ الذي تم فيه تصنيف معرّف الإعلان الشامل لتصميم الإعلان المحدّد.

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

يحتوي القسم "مصاحب" على معلومات عن الإعلانات المصاحبة التي قد يتم عرضها مع الإعلان.
تمثيل JSON
{
  "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)],
}
الحقول
click_data object(ClickData)

بيانات النقرات لهذا الفيديو المصاحب.
creative_type string

سمة CreativeType في عقدة <StaticResource> في ملف VAST إذا كان هذا إعلانًا مصاحبًا من النوع static
height int32

الارتفاع بالبكسل لهذا العنصر المصاحب.
width int32

عرض هذا العنصر المصاحب بالبكسل
resource string

بالنسبة إلى الإعلانات المصاحبة الثابتة وإعلانات iframe، سيكون هذا هو عنوان URL الذي سيتم تحميله وعرضه. بالنسبة إلى العناصر المصاحبة بتنسيق HTML، سيكون هذا هو مقتطف HTML الذي يجب عرضه كعنصر مصاحب.
type string

نوع هذا المصاحب. ويمكن أن يكون ثابتًا أو إطارًا iframe أو HTML.
ad_slot_id string

رقم تعريف خانة هذا الملحق.
api_framework string

إطار عمل واجهة برمجة التطبيقات لهذا الملحق
tracking_events [object(TrackingEvent)]

قائمة بأحداث التتبُّع لهذا الجهاز المصاحب

InteractiveFile

يحتوي InteractiveFile على معلومات عن تصميم الإعلان التفاعلي (أي SIMID) التي يجب عرضها أثناء تشغيل الإعلان.
تمثيل JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
الحقول
resource string

عنوان URL لتصميم الإعلان التفاعلي
type string

نوع MIME للملف المقدَّم كمصدر
variable_duration boolean

ما إذا كان تصميم الإعلان هذا قد يطلب تمديد المدة
ad_parameters string

قيمة عقدة <AdParameters> في ملف VAST