تتيح لك واجهة برمجة التطبيقات 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 رقم تعريف حدث مصدر البيانات. |
نص الطلب
نص الطلب من النوع application/x-www-form-urlencoded
ويحتوي على المَعلمات التالية:
المَعلمات | ||
---|---|---|
dai-ssb |
إجراء اختياري | اضبط القيمة على |
معلَمات استهداف مواضع الإعلانات | إجراء اختياري | معلمات استهداف إضافية. |
إلغاء مَعلمات مصدر البيانات | إجراء اختياري | إلغاء القيم التلقائية لمَعلمة إنشاء مصدر البيانات |
مصادقة 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). |