تتيح لك واجهة برمجة التطبيقات Dynamic Ad Insertion API طلب وتتبُّع عمليات بث الفيديوهات عند الطلب باستخدام DAI. يمكن البث عبر HLS وDASH.
الخدمة: dai.google.com
يرتبط مسار طريقة stream
بالمقياس https://dai.google.com
.
الطريقة: ساحة المشاركات
الطُرق | |
---|---|
stream |
POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
إنشاء بث HLS DAI لمصدر المحتوى ومعرّف الفيديو المحدّدَين
إنشاء بث DASH DAI لمصدر المحتوى ومعرّف الفيديو المحدّدَين |
طلب HTTP
POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream
عنوان الطلب
المعلمات | |
---|---|
api‑key |
string يجب أن يكون مفتاح واجهة برمجة التطبيقات الذي يتم تقديمه عند إنشاء مصدر بيانات صالحًا لشبكة الناشر. بدلاً من توفيره في نص الطلب، يمكن تمرير مفتاح واجهة برمجة التطبيقات في عنوان تفويض HTTP بالتنسيق التالي: Authorization: DCLKDAI key="<api-key>" |
مَعلمات المسار
المعلمات | |
---|---|
content-source |
string رقم تعريف نظام إدارة المحتوى الخاص بالبث. |
video-id |
string معرّف الفيديو للبث. |
نص الطلب
نص الطلب من النوع application/x-www-form-urlencoded
ويحتوي على المعلمات التالية:
المعلمات | ||
---|---|---|
dai-ssb |
اختيارية | اضبط القيمة على |
مَعلمات الاستهداف في DDEX | اختيارية | مَعلمات الاستهداف الإضافية |
إلغاء مَعلمات البث | اختيارية | إلغاء القيم التلقائية لمَعلمة إنشاء مصدر بيانات |
مصادقة HMAC | اختيارية | يمكنك المصادقة باستخدام رمز مميّز مستند إلى بروتوكول HMAC. |
نص الاستجابة
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على Stream
جديد. بالنسبة إلى أحداث البث التي تقدِّم إشارات من جهة الخادم، تحتوي Stream
هذه على حقلَي stream_id
وstream_manifest
فقط.
فتح القياس
يتضمّن الحقل Verifications
معلومات للتحقّق من
القياس المفتوح لمصادر البيانات التي لا تقدِّم إشارات من جهة الخادم.
يحتوي Verifications
على عنصر Verification
واحد أو أكثر يعرض الموارد والبيانات الوصفية
التي تحتاج إليها للتحقّق من تشغيل المواد الإبداعية باستخدام رمز قياس تابع لجهة خارجية.
يُسمَح باستخدام JavaScriptResource
فقط. لمزيد من المعلومات، يُرجى مراجعة مختبر IAB التقني ومواصفات نموذج عرض إعلانات الفيديو (VAST) 4.1.
الطريقة: التحقق من الوسائط
بعد العثور على معرِّف لوسائط الإعلانات أثناء التشغيل، يمكنك تقديم طلب على الفور باستخدام media_verification_url
من نقطة نهاية stream
. media_verification_url
هي مسار مطلق.
ولا تُعد طلبات التحقق من الوسائط ضرورية لأحداث البث التي تتضمن إشارات من جهة الخادم،
حيث يبدأ الخادم التحقق من الوسائط.
الطلبات المُرسَلة إلى نقطة النهاية media verification
ثابتة.
الطُرق | |
---|---|
media verification |
GET {media_verification_url}/{ad_media_id}
يتم إرسال إشعار إلى واجهة برمجة التطبيقات بحدث إثبات ملكية الوسائط. |
طلب HTTP
GET {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_"
.
ويجب إلحاق المحتوى النصي الكامل للإطار بالسمة media_verification_url لكل طلب تحقُّق من الإعلان.
أرقام تعريف وسائط الإعلانات (DASH)
سيتم إدراج معرّفات وسائط الإعلانات في البيان باستخدام عنصر EventStream
في DASH.
سيتضمّن كل EventStream
معرّف موارد منتظم (URI) لمعرّف المخطط بقيمة urn:google:dai:2018
.
وستشمل أحداثًا تشتمل على السمة messageData
التي تحتوي على
رقم تعريف وسائط إعلان يبدأ بـ “google_”
. يجب إلحاق محتوى السمة messageData
بالكامل بالسمة media_verification_url لكل
طلب لإثبات ملكية الإعلان.
بيانات الاستجابة
بث المحتوى
تُستخدَم ساحة المشاركات لعرض قائمة بجميع الموارد الخاصة بمصدر بيانات تم إنشاؤه حديثًا بتنسيق JSON .تمثيل JSON |
---|
{ "stream_id": string, "total_duration": number, "content_duration": number, "valid_for": string, "valid_until": string, "subtitles": [object(Subtitle)], "hls_master_playlist": string, "stream_manifest": string, "media_verification_url": string, "apple_tv": object(AppleTV), "ad_breaks": [object(AdBreak)], } |
الحقول | |
---|---|
stream_id |
string معرّف مصدر البيانات: |
total_duration |
number مدة البث بالثواني. |
content_duration |
number مدة المحتوى، بدون إعلانات، بالثواني |
valid_for |
string البث المباشر مدّته صالح بالتنسيق "00h00m00s". |
valid_until |
string تاريخ سريان البث حتى يكون بالتنسيق RFC 3339. |
subtitles |
[object(Subtitle)] قائمة الترجمة: يتم حذفها إذا كانت فارغة. بروتوكول HLS فقط |
hls_master_playlist |
string (تم إيقاف هذا الخيار) عنوان URL لقائمة التشغيل الرئيسية في بروتوكول HLS. استخدِم Stream_manifest. بروتوكول HLS فقط |
stream_manifest |
string بيان ساحة المشاركات: يتطابق مع قائمة التشغيل الرئيسية في HLS وMPD في DASH. هذا هو الحقل الوحيد إلى جانب "stream_id" الموجود في الاستجابة عند إنشاء بث إشارة من جهة الخادم. |
media_verification_url |
string عنوان URL للتحقق من الوسائط |
apple_tv |
object(AppleTV) معلومات اختيارية خاصة بأجهزة AppleTV بروتوكول HLS فقط |
ad_breaks |
[object(AdBreak)] قائمة بالفواصل الإعلانية: يتم حذفها إذا كانت فارغة. |
AppleTV
يحتوي AppleTV على معلومات خاصة بأجهزة Apple TV.تمثيل JSON |
---|
{ "interstitials_url": string, } |
الحقول | |
---|---|
interstitials_url |
string عنوان URL للإعلانات البينية: |
AdBreak
تصف AdBreak فاصلاً إعلانيًا واحدًا في البث. وتحتوي على موضع ومدة ونوع (منتصف/قبل/نشر) وقائمة بالإعلانات.تمثيل JSON |
---|
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], } |
الحقول | |
---|---|
type |
string أنواع الفواصل الصالحة هي: في منتصفها أو قبلها أو بعدها. |
start |
number تحديد موضع الفاصل في البث المباشر بالثواني: |
duration |
number مدة الفاصل الإعلاني بالثواني. |
ads |
[object(Ad)] قائمة بالإعلانات: يتم حذفها إذا كانت فارغة. |
إعلان
يصف الإعلان إعلانًا أثناء البث. وهي تشمل موضع الإعلان عند الفاصل ومدته وبعض البيانات الوصفية الاختيارية.تمثيل JSON |
---|
{ "seq": number, "start": 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, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "events": [object(Event)], "verifications": [object(Verification)], "universal_ad_id": object(UniversalAdID), "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
الحقول | |
---|---|
seq |
number موضع الإعلان في الفاصل. |
start |
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 عنوان URL اختياري للنقر. |
icons |
[object(Icon)] قائمة بالرموز، يتم حذفها إذا كانت فارغة: |
wrappers |
[object(Wrapper)] قائمة بالأغلفة. يتم حذفها إذا كانت فارغة. |
events |
[object(Event)] قائمة بالأحداث في الإعلان |
verifications |
[object(Verification)] إدخالات اختيارية لإثبات الملكية باستخدام "القياس المفتوح" تتضمّن الموارد والبيانات الوصفية المطلوبة لتنفيذ رمز القياس التابع لجهة خارجية من أجل التحقّق من تشغيل المواد الإبداعية |
universal_ad_id |
object(UniversalAdID) رقم تعريف الإعلان العام الاختياري. |
companions |
[object(Companion)] الإعلانات المصاحبة الاختيارية التي يمكن عرضها مع هذا الإعلان. |
interactive_file |
object(InteractiveFile) تصميم إعلان تفاعلي اختياري (SIMID) يجب عرضه أثناء تشغيل الإعلان |
حدث
يحتوي الحدث على نوع حدث ووقت لعرضه.تمثيل JSON |
---|
{ "time": number, "type": string, } |
الحقول | |
---|---|
time |
number وقت العرض التقديمي لهذه الفعالية |
type |
string نوع هذا الحدث. |
العنوان الفرعي
يصف العنوان الفرعي مسار الترجمة المصاحبة للفيديو الجانبي. وهو يخزن تنسيقين للترجمة: TTML وWebVTT. تضم سمة TTMLPath عنوان URL الخاص بملف TTML الجانبي، كما تحتوي سمة WebVTTPath على عنوان URL أيضًا على عنوان ملف WebVTT الجانبي.تمثيل JSON |
---|
{ "language": string, "language_name": string, "ttml": string, "webvtt": string, } |
الحقول | |
---|---|
language |
string رمز لغة، مثل "en" أو "de" |
language_name |
string الاسم الوصفي للغة: يميز المجموعة المحددة من الترجمة في حالة وجود مجموعات متعددة لنفس اللغة |
ttml |
string عنوان URL اختياري لملف TTML الجانبي. |
webvtt |
string عنوان URL اختياري لملف WebVTT الجانبي. |
الرمز
يحتوي الرمز على معلومات حول رمز نموذج عرض إعلانات فيديو (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 رقم تعريف الصفقة الاختياري لإعلان التضمين. |
التحقّق
تحتوي عملية التحقق على معلومات للقياس المفتوح، والتي تُسهل قياس إمكانية العرض والتحقق من طرف ثالث. في الوقت الحالي، تتوفّر موارد 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
يحتوي TrackEvent على عناوين 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) إذا كانت مصاحبة من النوع الثابت. |
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 قيمة العقدة <Adparams> في VAST |