تتيح لك واجهة برمجة التطبيقات 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 |
اختيارية | اضبط القيمة على |
مَعلمات الاستهداف في 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 |