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

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

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

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

الطريقة: stream

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

تسجّل هذه السمة مجموعة إعلانات أثناء البث المباشر تعرض جلسة بث مباشر.

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

Open Measurement

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

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

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

  • يجب أن يتراوح طولها بين حرف واحد و63 حرفًا
  • يجب أن يحتوي على أحرف صغيرة وأرقام وواصلات فقط.
profile_name string

تمثّل هذه السمة اسم ملف ترميز "إعلانات البث المباشر" في "مدير إعلانات 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

يتألف auth-token من رمز HMAC مشفّر يتضمّن البيانات التالية:

  • pod_id أو ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp
last اختيارية boolean

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

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

مجموعة من أزواج المفاتيح والقيم، تُستخدَم لاستهداف الحملات في "مدير إعلانات Google". يجب تمثيل هذه الأزواج كسلسلة طلب بحث مرمَّزة بنظام عناوين 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}

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

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

  • يجب أن يتراوح طولها بين حرف واحد و63 حرفًا
  • يجب أن يحتوي على أحرف صغيرة وأرقام وواصلات فقط.

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

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

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

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

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

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

مثال:
المعلمات
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...
auth-token مطلوب string

يتألف auth-token من رمز HMAC مشفّر يتضمّن البيانات التالية:

  • pod_id أو ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp

نص الاستجابة

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

الطريقة: بيان حزمة DASH

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

الطُرق
GET GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/{pod_identifier}/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_identifier

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

pod/{integer}

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

ad_break_id/{string}

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

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

  • يجب أن يتراوح طولها بين حرف واحد و63 حرفًا
  • يجب أن يحتوي على أحرف صغيرة وأرقام وواصلات فقط.

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

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

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

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

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

مثال:
المعلمات
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...
auth-token مطلوب string

يتألف auth-token من رمز HMAC مشفّر يتضمّن البيانات التالية:

  • pod_id أو ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp

نص الاستجابة

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

الطريقة: نموذج فترة مجموعة إعلانات 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.
tv اختيارية integer

إصدار النموذج القيمة التلقائية هي 0. تحدّد هذه السمة إصدار نموذج الحزمة المطلوب عرضه.

  • 0: يطلب نموذجًا يستخدم معرّف تسلسل مجموعة الإعلانات المتسلسلة.
  • ‫1: يطلب نموذجًا يتوافق مع كل من تسلسل الإعلانات المتتالية ومعرّفات فواصل الإعلانات.

نص الاستجابة

في حال نجاح العملية، سيحتوي نص الاستجابة على عنصر جديد 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

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

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

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

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

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

يتألف auth-token من رمز HMAC مشفّر يتضمّن البيانات التالية:

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

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

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

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

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

القيمة التلقائية هي 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 إذا نجحت عملية التحقّق من صحة الوسائط وتم إرسال جميع طلبات Ping
  • ‫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}

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

المعلمات
delta_token اختيارية string

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

نص الاستجابة

في حال نجاح العملية، تعرض الاستجابة مثالاً على 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 لعمليات التحقّق من النشاط، والذي يُستخدَم لإبقاء بث إشارات الخادم نشطًا، يجب إرسال طلب ping إليه كل {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)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
الحقول
tags map[string, object(TagSegment)]

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

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

خريطة الفواصل الإعلانية مفهرسة حسب رقم تعريف الفاصل الإعلاني.
next_delta_token string

يشير إلى رمز مميز ومبهم يمكن للعميل استخدامه في عملية الاستطلاع التالية.
obsolete_ad_break_ids string

قائمة بمعرّفات فواصل الإعلانات التي أصبحت قديمة ويجب إزالتها من ذاكرة التخزين المؤقت للعميل.

TagSegment

يحتوي TagSegment على مرجع إلى إعلان وفاصل إعلاني ونوع حدث. يجب عدم إرسال طلبات ping إلى نقطة نهاية التحقّق من وسائط الإعلان الخاصة بـ 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)]

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

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

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

قائمة بالبرامج المغلّفة، يتم حذفها إذا كانت فارغة.
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)]

قائمة بمجموعات التكيّف مع البث المتكيّف الديناميكي عبر HTTP (DASH) لمجموعة الإعلانات المتسلسلة هذه التي سيتم عرضها في بيانات DASH.

AdRendering

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

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

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

SlateRendering

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

مدة لوحة الإعلانات بالمللي ثانية (عدد صحيح).
variants map[string, object(VariantRendering)]

قاموس لعناصر Variant، مفهرس حسب معرّف خيار المنتج/الملف الشخصي. يجب تكرار مدة اللوحة الإعلانية إلى أن يتم بلوغ طول اللوحة الإعلانية المطلوب، مع إدراج فواصل 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

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

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

DASHRepresentation

يصف DASHRepresentation عقد Representation التي سيتم عرضها في بيانات 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

يحتوي برنامج التضمين على معلومات عن إعلان برنامج تضمين. ولا يتضمّن رقم تعريف صفقة إذا لم يكن متوفّرًا.
تمثيل 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

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

التحقق

يتضمّن التحقّق معلومات عن Open Measurement، ما يسهّل قياس إمكانية العرض والتحقّق من الطرف الثالث. في الوقت الحالي، لا تتوفّر سوى موارد 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 الخاص بالموقع الإلكتروني الخاص بالسجلّ الذي تم فيه إدراج المعرّف العالمي للإعلان الخاص بتصميم الإعلان المحدّد.

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

يحتوي العنصر Companion على معلومات للإعلانات المصاحبة التي يمكن عرضها مع الإعلان.
تمثيل 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 إذا كان هذا إعلانًا مصاحبًا من النوع الثابت
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