واجهة برمجة التطبيقات المباشرة التي تعرض لوحة "إدراج إعلان ديناميكي"

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

الخدمة: dai.google.com

ترتبط جميع معرّفات الموارد المنتظمة (URI) بـ https://dai.google.com.

الطريقة: ساحة المشاركات

الطُرق
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

تسجيل جلسة بث مباشر تعرض مجموعة DAI DAI

طلب HTTP

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

مَعلمات المسار

المعلمات
network_code string

رمز شبكة "مدير إعلانات Google" للناشر

custom_asset_key string

المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google"

نص الطلب

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

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

نص الاستجابة

في حال نجاح الإجراء، يحتوي نص الاستجابة على كائن Stream جديد.

فتح القياس

تحتوي DAI API على معلومات لإثبات صحة بيانات القياس المفتوح في Verifications. يحتوي هذا الحقل على حقل واحد أو أكثر عناصر Verification التي تسرد الموارد والبيانات الوصفية المطلوبة للتنفيذ رمز القياس التابع لجهة خارجية للتحقّق من تشغيل المواد الإبداعية. فقط يُسمح باستخدام JavaScriptResource. لمزيد من المعلومات، يُرجى الاطّلاع على مختبر IAB التقني مواصفات VAST 4.1:

الطريقة: شريحة المجموعة

الطُرق
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

ينشئ هذا الإعداد ساحة مشاركات DAI لمعرّف الحدث المحدّد.

طلب HTTP

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

مَعلمات المسار

المعلمات
network_code string

رمز شبكة "مدير إعلانات Google" للناشر

custom_asset_key string

المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google"

pod_id integer

المعرّف الرقمي للفاصل الإعلاني الحالي. أرقام تعريف مجموعات الإعلانات المتسلسلة هي المخصص بشكل تدريجي لكل حدث، بدءًا من 1.
profile_name string

تشير رسالة الأشكال البيانية الاسم مما هو مطلوب الملف الشخصي لترميز DAI في "مدير إعلانات Google": يجب أن يكون ملف الترميز أحد ملفات الترميز الشخصية التي تم إعدادها. الحدث المحدد.

segment_number integer

فهرس الشريحة المطلوبة ضمن مجموعة الإعلانات المتسلسلة الحالية، بدءًا من إلى الصفر.
segment_format string

امتداد الملف المرتبط بتنسيق المقطع المطلوب. الإضافات المقبولة هي: "ts" و"mp4" و vtt أو aac أو ac3 أو eac3

معامِلات طلب البحث

المعلمات
stream_id مطلوب string

رقم تعريف مصدر البيانات لجلسة المستخدم الحالي يتم عرض هذه القيمة من خلال إرسال طلب ناجح إلى نقطة النهاية stream.
sd required1 integer

مدة المقطع المطلوب بالمللي ثانية.
so اختيارية

إزاحة الشريحة المطلوبة داخل مجموعة الإعلانات المتسلسلة بالمللي ثانية إذا لم يتم إدراج مَعلمة so، سيتم احتسابها من خلال النحو التالي: ضرب مدة الشريحة في رقم الجزء.
pd مطلوبة2 integer

مدة مجموعة الإعلانات المتسلسلة بالمللي ثانية.
auth-token مطلوب string

ملف موقع وبترميز url رمز HMAC المميز لمجموعة الإعلانات المتسلسلة الحالية
last اختيارية boolean

يشير إلى آخر شريحة في الفاصل الإعلاني. حذف هذه المعلمة للكل الأقسام الأخرى.
scte35 اختيارية string

SCTE-35signal بترميز Base64 لهذا الفاصل الإعلاني.
cust_params اختيارية string

مجموعة من أزواج المفتاح/القيمة تُستخدَم لاستهداف حملات "مدير إعلانات Google". هذه يجب تمثيل الأزواج كسلسلة طلب بحث مرمّزة بعنوان URL.

مثال:
المعلمات
  • القسم = sports
  • الصفحة = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

الحواشي السفلية

  1. لا يلزم استخدام sd لشرائح الإعداد. ↩
  2. pd ليس مطلوبًا للأحداث التي تحتوي على إعلان غير محدد المدة. تم تفعيل الفواصل. ↩

نص الاستجابة

في حال نجاح الردّ، سيكون نص الاستجابة مقطعًا من ساحة المشاركات قابل للتشغيل ومطابقًا التنسيق والمعلمات المحددة في الطلب.

الطريقة: نموذج فترة مجموعة DASH

الطُرق
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

تطلب نموذج فترة DASH من "مدير إعلانات Google". هذا النموذج يحتوي على وحدات ماكرو يجب تعبئتها بمعلمات البث. مرة واحدة تعبئة وحدات الماكرو هذه، وسيصبح النموذج فترة الفاصل الإعلاني في بيان DASH.

طلب HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

مَعلمات المسار

المعلمات
network_code string

رمز شبكة "مدير إعلانات Google" للناشر

custom_asset_key string

المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google"

معامِلات طلب البحث

المعلمات
stream_id مطلوب string

رقم تعريف مصدر البيانات لجلسة المستخدم الحالي يتم عرض هذه القيمة من خلال إرسال طلب ناجح إلى نقطة النهاية stream.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على PodTemplateResponse.

الطريقة: التحقق من الوسائط

بعد العثور على معرّف لوسائط الإعلانات أثناء التشغيل، طلب باستخدام 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 أو emsg لملفات mp4 معرّفات وسائط الإعلانات ستبدأ دائمًا بالسلسلة 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,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
الحقول
stream_id string

معرّف مصدر البيانات في "مدير إعلانات Google"
media_verification_url string

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

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

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

عنوان URL لنبضات القلب، الذي يُستخدم لمواصلة بث الإشارات من جهة الخادم يجب إرسال الاتصال كل {PollingFrequency} ثانية. وتتم تعبئة تلك البيانات لأحداث البث التي تتضمّن إشارات من جهة الخادم.
polling_frequency number

معدّل تكرار الاستطلاع بالثواني عند طلب البيانات الوصفية_url أو Heartbeat_url.
pod_manifest_url string

يُستخدم نموذج عنوان URL الخاص ببيان مجموعة الإعلانات المتسلسلة لإنشاء عنوان URL لاسترداد بيان مجموعة البث. مطابق لعنوان URL لقائمة تشغيل متعددة المتغيرات في HLS أو MPD في DASH. تتم تعبئة هذا الحقل لأحداث البث المباشر من النوع "إدراج إعلان ديناميكي" POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

"تنسيق البيان" هو تنسيق البيان الذي تم استرداده من pod_manifest_url، إما شرطة أو hls.

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 with 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) الذي يجب عرضه أثناء تشغيل الإعلان

PodTemplateResponse

يمثل PodTemplateResponse حمولة JSON التي يتم إرجاعها إلى VTP لدمج مجموعة الأجهزة.
تمثيل JSON
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
الحقول
dash_period_template string

DashPeriodTemplate هو نموذج XML الذي يتم استخدامه لملء الفترة بالبيانات المناسبة قبل الدمج.
segment_duration_ms int64

SegmentDurationMS هي مدة شرائح الفترات بالمللي ثانية.

الرمز

يحتوي الرمز على معلومات حول رمز نموذج عرض إعلانات فيديو (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)