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

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

الخدمة: 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

رقم تعريف حدث البث
ملاحظة: مفتاح مادة عرض البث هو معرّف يمكن العثور عليه أيضًا في واجهة مستخدم "مدير إعلانات Google".

نص الطلب

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

المعلمات
dai-ssb اختيارية

اضبط القيمة على true لإنشاء بث إشارة من جهة الخادم. وتكون القيمة التلقائية هي false. ويبدأ العميل عملية تتبّع البث التلقائي ويتم إرسال إشارة إليه من جهة الخادم.
مَعلمات الاستهداف في 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

(تم الإيقاف) عنوان URL لقائمة تشغيل متعددة المتغيرات في بروتوكول HLS. استخدِم "stream_manifest" بدلاً من ذلك.
media_verification_url string

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

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

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

معدّل تكرار الاستطلاع بالثواني عند طلب البيانات الوصفية_url من أو إدخال lightbeat_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 مع 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