تتيح لك واجهة برمجة التطبيقات Dynamic Ad Insertion API طلب ميزة "إدراج إعلان ديناميكي" وتتبُّعها أحداث البث المباشر غير القابلة للتقديم أو الإيقاف
الخدمة: dai.google.com
ترتبط كل معرّفات الموارد المنتظمة (URI) التالية بالموقع الإلكتروني https://dai.google.com
.
الطريقة: ساحة المشاركات
الطُرق | |
---|---|
stream |
POST /linear/v1/hls/event/{assetKey}/stream
ينشئ هذا الإعداد ساحة مشاركات DAI لمعرّف الحدث المحدّد. |
طلب HTTP
POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream
عنوان الطلب
المعلمات | |
---|---|
api‑key |
string مفتاح واجهة برمجة التطبيقات الذي يتم تقديمه عند إنشاء بث أن تكون صالحة لشبكة الناشر. يمكن تمرير مفتاح واجهة برمجة التطبيقات بدلاً من توفيره في نص الطلب في عنوان تفويض HTTP بالتنسيق التالي: Authorization: DCLKDAI key="<api-key>" |
مَعلمات المسار
المعلمات | |
---|---|
assetKey |
string رقم تعريف حدث البث |
نص الطلب
نص الطلب من النوع application/x-www-form-urlencoded
ويحتوي على
المَعلمات التالية:
المعلمات | ||
---|---|---|
dai-ssb |
اختياري | اضبط القيمة على |
مَعلمات الاستهداف في DDEX | اختياري | مَعلمات الاستهداف الإضافية |
إلغاء مَعلمات البث | اختياري | إلغاء القيم التلقائية لمَعلمة إنشاء مصدر بيانات |
مصادقة HMAC | اختياري | عليك المصادقة باستخدام رمز مميّز مستند إلى بروتوكول HMAC. |
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على
Stream
بالنسبة إلى أحداث البث التي تقدِّم إشارات من جهة الخادم، إنّ حدث Stream
هذا
يحتوي على الحقلين stream_id
وstream_manifest
فقط.
فتح القياس
تحتوي DAI API على معلومات لإثبات صحة بيانات القياس المفتوح في
Verifications
. يحتوي هذا الحقل على حقل واحد أو أكثر
عناصر Verification
التي تسرد الموارد والبيانات الوصفية المطلوبة للتنفيذ
رمز القياس التابع لجهة خارجية للتحقّق من تشغيل المواد الإبداعية. فقط
يُسمح باستخدام JavaScriptResource
. لمزيد من المعلومات، يُرجى الاطّلاع على
مختبر IAB التقني
مواصفات VAST 4.1:
الطريقة: التحقق من الوسائط
بعد العثور على معرّف لوسائط الإعلانات أثناء التشغيل، طلب باستخدام media_verification_url التي تم الحصول عليها من ساحة المشاركات نقطة نهاية أعلى. هذه الطلبات ليست ضرورية لإجراء إشارة من جهة الخادم عمليات البث، حيث يبدأ الخادم التحقق من الوسائط.
الطلبات المُرسَلة إلى نقطة النهاية 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)
سيتم ترميز معرّفات وسائط الإعلانات في البيانات الوصفية المستندة إلى HLS باستخدام المفتاح
TXXX
، محجوز لـ "معلومات النص التي يحددها المستخدم" الإطارات. تشير رسالة الأشكال البيانية
سيتم فك تشفير محتوى الإطار وسيبدأ دائمًا بالنص
"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, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, } |
الحقول | |
---|---|
stream_id |
string معرّف مصدر البيانات في "مدير إعلانات Google" |
stream_manifest |
string عنوان URL الخاص ببيان البث، ويُستخدَم لاسترداد قائمة التشغيل ذات المتغيرات المتعددة في HLS أو MPD في DASH |
hls_master_playlist |
string (DEPRECATED) عنوان URL لقائمة تشغيل HLS متعددة المتغيرات. استخدام "stream_manifest" بدلاً من ذلك. |
media_verification_url |
string عنوان URL للتحقق من الوسائط المستخدَم كنقطة نهاية أساسية لتتبُّع أحداث التشغيل |
metadata_url |
string عنوان URL للبيانات الوصفية يتم استخدامه لإجراء استطلاع للحصول على المعلومات الدورية حول أحداث إعلانات البث القادمة. |
session_update_url |
string عنوان URL لتعديل الجلسة المستخدَم لتعديل مَعلمات الاستهداف لمصدر البيانات هذا. يتم تسجيل القيم الأصلية لمَعلمات الاستهداف أثناء طلب إنشاء البث الأوّلي. |
polling_frequency |
number معدّل تكرار الاستطلاع بالثواني عند طلب البيانات الوصفية_url أو Heartbeat_url. |
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 with 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)] قائمة ببرامج الالتفاف، يتم حذفها إذا كانت فارغة. |
universal_ad_id |
object(UniversalAdID) رقم تعريف الإعلان العام الاختياري: |
extensions |
string قائمة اختيارية بجميع <الإضافة> في نموذج عرض إعلانات الفيديو (VAST) |
companions |
[object(Companion)] الإعلانات المصاحبة الاختيارية التي يمكن عرضها مع هذا الإعلان. |
interactive_file |
object(InteractiveFile) تصميم الإعلان التفاعلي الاختياري (SIMID) الذي يجب عرضه أثناء تشغيل الإعلان |
الرمز
يحتوي الرمز على معلومات حول رمز نموذج عرض إعلانات فيديو (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) |