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

تتيح لك واجهة برمجة التطبيقات 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. يتم تتبُّع مصدر البيانات التلقائي من خلال العميل ويتم إرسال إشعار إليه من جهة الخادم.
مَعلمات استهداف DoubleClick اختيارية مَعلمات الاستهداف الإضافية
إلغاء مَعلمات مصدر البيانات اختيارية إلغاء القيم التلقائية لمَعلمة إنشاء مصدر البيانات
مصادقة 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 أو 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 with 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

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

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

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