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

تتيح لك واجهة برمجة التطبيقات 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. يتم تتبُّع البث التلقائي من خلال العميل ويتم إرسال إشعار إليه من جهة الخادم.

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

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على العنصر الجديد Stream. بالنسبة إلى ساحات المشاركات من جهة الخادم، لا تحتوي سمة Stream هذه على حقلَي stream_id وstream_manifest إلا.

فتح عملية القياس

تحتوي واجهة برمجة تطبيقات DAI على معلومات حول التحقق من القياس المفتوح في الحقل 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

معرّف مصدر البيانات:
stream_manifest string

ملف بيان مجموعة البث، والذي يتوافق مع قائمة التشغيل الرئيسية في HLS أو MPD في DASH. هذا هو الحقل الوحيد إلى جانب "stream_id" الذي يظهر في الاستجابة عند إنشاء بث الإشارة من جهة الخادم.
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 للبيانات الوصفية المقترَح، بالثواني

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

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

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

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

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

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

قائمة اختيارية بجميع عُقد <Extension> في نموذج عرض إعلانات الفيديو (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

تحتوي الصورة الاحتياطية على معلومات حول صورة 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

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

نوع حدث التتبّع، الخيار الوحيد المتاح حاليًا هو verificationNotExecuted" على النحو المحدّد في مواصفات VAST 4.1.
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,
}
الحقول
click_data object(ClickData)

بيانات النقرات لهذا الإعلان المصاحب
creative_type string

سمة CreativeType في العقدة <StaticResource> في نموذج عرض إعلانات الفيديو (VAST) إذا كان هذا العنصر مصاحبًا من النوع الثابت.
height int32

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

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

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

نوع هذا الرفيق. ويمكن أن يكون العنوان ثابتًا أو إطار iframe أو HTML.

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).