Dynamic Ad Insertion VOD API

با میانای برنامه‌سازی کاربردی «درج آگهی پویا» می‌توانید جاری‌سازی‌های ویدیو به‌درخواست (VOD) «درج آگهی پویا» را درخواست و ردیابی کنید. جاری‌سازی‌های HLS و DASH پشتیبانی می‌شوند.

سرویس: dai.google.com

مسیر روش stream نسبت‌به https://dai.google.com است

روش: جاری‌سازی

روش‌ها
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

جاری‌سازی HLS DAI برای منبع محتوا و شناسه ویدیو داده‌شده ایجاد می‌کند.

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

جریان DASH DAI برای منبع محتوا و شناسه ویدیو داده‌شده ایجاد می‌کند.

درخواست HTTP

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

سرصفحه درخواست

پارامترها
api‑key string

کلید میانای برنامه‌سازی کاربردی که هنگام ایجاد جاری‌سازی ارائه می‌شود، باید برای شبکه ناشر معتبر باشد.

به‌جای ارائه کلید API در بدنه درخواست، می‌توان آن را در سرصفحه «مجوز HTTP» با قالب زیر ارسال کرد:

Authorization: DCLKDAI key="<api-key>"

پارامترهای مسیر

پارامترها
content-source string

شناسه CMS جاری‌سازی.

video-id string

شناسه ویدیو جاری‌سازی.

متن درخواست

بدنه درخواست از نوع application/x-www-form-urlencoded است و حاوی پارامترهای زیر است:

پارامترها
dai-ssb اختیاری

برای ایجاد جاری‌سازی فانوس‌گذاری سمت سرور، روی true تنظیم کنید. پیش‌فرض‌ها به false. ردیابی جاری‌سازی پیش‌فرض توسط کارخواه شروع می‌شود و در سمت سرور پینگ می‌شود.
پارامترهای هدف‌یابی DFP اختیاری پارامترهای هدف‌یابی بیشتر.
لغو پارامترهای جاری‌سازی اختیاری مقادیر پیش‌فرض پارامتر ایجاد جاری‌سازی را لغو کنید.
اصالت‌سنجی HMAC اختیاری اصالت‌سنجی بااستفاده از یک کد HMAC.

بدنه پاسخ

اگر موفقیت‌آمیز باشد، بدنه پاسخ حاوی Stream جدیدی است. برای جاری‌سازی‌های ارسال چراغک از سمت سرور، این Stream فقط حاوی فیلدهای stream_id و stream_manifest است.

اندازه‌گیری باز

فیلد Verifications حاوی اطلاعاتی برای درستی‌سنجی «اندازه‌گیری باز» برای جاری‌سازی‌های غیرسمت سرور است. Verifications حاوی یک یا چند عنصر Verification است که منابع و فراداده‌های موردنیاز شما را برای درستی‌سنجی بازپخش آگهی با کد سنجش طرف سوم فهرست می‌کند. فقط از JavaScriptResource پشتیبانی می‌شود. برای اطلاعات بیشتر، IAB Tech Lab و مشخصات VAST 4.1 را ببینید.

روش: درستی‌سنجی رسانه

پس‌از مواجه شدن با شناسه رسانه آگهی درطول بازپخش، بلافاصله بااستفاده از media_verification_url از نقطه پایانی stream درخواست کنید. ‫media_verification_url یک مسیر مطلق است. درخواست‌های درستی‌سنجی رسانه برای جاری‌سازی‌های beaconing سمت سرور لازم نیست، جایی که سرور درستی‌سنجی رسانه را آغاز می‌کند.

درخواست‌ها به نقطه پایان media verification یکسان‌اثر هستند.

روش‌ها
media verification GET {media_verification_url}/{ad_media_id}

رویداد درستی‌سنجی رسانه را به میانای برنامه‌سازی کاربردی اطلاع می‌دهد.

درخواست HTTP

GET {media-verification-url}/{ad-media-id}

بدنه پاسخ

media verification پاسخ‌های زیر را برمی‌گرداند:

  • HTTP/1.1 204 No Content اگر درستی‌سنجی رسانه موفقیت‌آمیز باشد و همه پینگ‌ها ارسال شده باشند.
  • HTTP/1.1 404 Not Found اگر درخواست نتواند رسانه را به‌دلیل قالب‌بندی نادرست نشانی وب یا انقضا درستی‌سنجی کند.
  • HTTP/1.1 404 Not Found اگر درخواست درستی‌سنجی قبلی برای این شناسه موفقیت‌آمیز بوده است.
  • HTTP/1.1 409 Conflict اگر درخواست دیگری درحال‌حاضر درحال ارسال پینگ باشد.

شناسه‌های رسانه آگهی (HLS)

شناسه‌های رسانه آگهی در «فراداده زمان‌بندی‌شده HLS» بااستفاده از کلید TXXX کدگذاری خواهد شد، که برای قاب‌های «اطلاعات نوشتاری تعریف‌شده توسط کاربر» رزرو شده است. محتوای قاب رمزگشایی خواهد شد و همیشه با نوشتار "google_" شروع می‌شود.

کل محتوای نوشتاری قاب باید به media_verification_url برای هر درخواست درستی‌سنجی آگهی اضافه شود.

شناسه‌های رسانه آگهی (DASH)

شناسه‌های رسانه آگهی بااستفاده از عنصر EventStream DASH در مانیفست درج خواهد شد.

هر EventStream دارای یک شناسه منبع یکسان (URI) شناسه طرح urn:google:dai:2018 خواهد بود. این رویدادها حاوی رویدادهایی با مشخصه messageData خواهند بود که حاوی شناسه رسانه آگهی است که با "google_" شروع می‌شود. کل محتوای مشخصه messageData باید به media_verification_url برای هر درخواست درستی‌سنجی آگهی اضافه شود.

داده‌های پاسخ

آبی رودخانه‌ای

از «جاری‌سازی» برای ارائه فهرست همه منابع برای جاری‌سازی جدید ایجادشده در قالب JSON استفاده می‌شود .
نمایش JSON
{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}
فیلدها
stream_id string

شناسه جاری‌سازی.
total_duration number

مدت جاری‌سازی برحسب ثانیه.
content_duration number

مدت محتوا، بدون آگهی، به ثانیه.
valid_for string

مدت‌زمانی که جاری‌سازی برای آن معتبر است، در قالب «00h00m00s».
valid_until string

تاریخی که جاری‌سازی تا آن زمان معتبر است، در قالب RFC 3339.
subtitles [object(Subtitle)]

فهرستی از زیرنویس‌ها. اگر خالی باشد، حذف می‌شود. فقط HLS.
hls_master_playlist string

(منسوخ‌شده) نشانی وب فهرست پخش اصلی HLS. از stream_manifest استفاده کنید. فقط HLS.
stream_manifest string

مانیفست جاری‌سازی. مطابق با فهرست پخش اصلی در HLS و MPD در DASH. این تنها فیلد علاوه‌بر «stream_id» است که هنگام ایجاد جاری‌سازی چراغک سمت سرور در پاسخ وجود دارد.
media_verification_url string

نشانی وب درستی‌سنجی رسانه.
apple_tv object(AppleTV)

اطلاعات اختیاری مختص دستگاه‌های AppleTV. فقط HLS.
ad_breaks [object(AdBreak)]

فهرستی از AdBreaks. اگر خالی باشد، حذف می‌شود.

AppleTV

AppleTV حاوی اطلاعات مختص دستگاه‌های Apple TV است.
نمایش JSON
{
  "interstitials_url": string,
}
فیلدها
interstitials_url string

نشانی وب بینابینی.

AdBreak

AdBreak یک وقفه آگهی را در جاری‌سازی توصیف می‌کند. این شیء حاوی موقعیت، مدت، نوع (میان/پیش/پس)، و فهرستی از آگهی‌ها است.
نمایش JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
فیلدها
type string

انواع معتبر وقفه عبارتند از: میانی، پیش، و پس.
start number

موقعیت در جاری‌سازی که وقفه شروع می‌شود، برحسب ثانیه.
duration number

مدت وقفه آگهی، به ثانیه.
ads [object(Ad)]

فهرست آگهی‌ها. اگر خالی باشد، حذف می‌شود.
آگهی، آگهی‌ای را در جاری‌سازی توصیف می‌کند. این رویداد حاوی جایگاه آگهی در وقفه، مدت آگهی، و برخی فراداده‌های اختیاری است.
نمایش JSON
{
  "seq": number,
  "start": 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,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}
فیلدها
seq number

جایگاه آگهی در وقفه.
start 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

نشانی وب کلیک‌گذری اختیاری.
icons [object(Icon)]

فهرستی از نمادها، اگر خالی باشد حذف می‌شود.
wrappers [object(Wrapper)]

فهرستی از Wrapperها. اگر خالی باشد، حذف می‌شود.
events [object(Event)]

فهرست رویدادهای آگهی.
verifications [object(Verification)]

ورودی‌های درستی‌سنجی «سنجش باز» اختیاری که منابع و فراداده‌های لازم برای اجرای کد سنجش طرف سوم را برای درستی‌سنجی بازپخش طرح آگهی فهرست می‌کند.
universal_ad_id object(UniversalAdID)

شناسه آگهی جهانی اختیاری.
companions [object(Companion)]

همراهان اختیاری که ممکن است همراه با این آگهی نمایش داده شوند.
interactive_file object(InteractiveFile)

طرح‌آگهی تعاملی اختیاری (SIMID) که باید درطول بازپخش آگهی نمایش داده شود.
skip_metadata object(SkipMetadata)

فراداده اختیاری برای آگهی‌های ردشدنی. اگر تنظیم شود، نشان می‌دهد که آگهی ردشدنی است و شامل دستورالعمل‌هایی برای نحوه مدیریت واسط کاربر رد کردن و رویداد ردیابی است.
extensions string

فهرست اختیاری همه گره‌های <Extension> در VAST.

رویداد

رویداد شامل نوع رویداد و زمان ارائه رویداد است.
نمایش JSON
{
  "time": number,
  "type": string,
}
فیلدها
time number

زمان ارائه این رویداد.
type string

نوع این رویداد.

زیرنویس

زیرنویس، قطعه زیرنویس جانبی را برای جاری‌سازی ویدیو توصیف می‌کند. این فایل دو قالب زیرنویس را ذخیره می‌کند: TTML و WebVTT. شاخصه TTMLPath حاوی نشانی وب فایل جانبی TTML است و شاخصه WebVTTPath نیز به‌طور مشابه حاوی نشانی وب فایل جانبی WebVTT است.
نمایش JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
فیلدها
language string

کد زبان، مثل «en» یا «de».
language_name string

نام توصیفی زبان. اگر چند مجموعه زیرنویس برای یک زبان وجود داشته باشد، این برچسب مجموعه خاص را متمایز می‌کند
ttml string

نشانی وب اختیاری برای فایل TTML جانبی.
webvtt string

نشانی وب اختیاری برای فایل جانبی WebVTT.

SkipMetadata

SkipMetadata اطلاعات لازم را برای کارخواه‌ها فراهم می‌کند تا بتوانند رویدادهای رد کردن را برای آگهی‌های ردکردنی مدیریت کنند.
نمایش JSON
{
  "offset": number,
  "tracking_url": string,
}
فیلدها
offset number

انحراف نشان‌دهنده مدت زمانی به ثانیه است که پخش‌کننده باید در آگهی منتظر بماند تا دکمه رد شدن را ارائه دهد. اگر در VAST ارائه نشده باشد، حذف می‌شود.
tracking_url string

TrackingURL حاوی نشانی وبی است که باید در رویداد رد شدن پینگ شود.

نماد

نماد حاوی اطلاعاتی درباره نماد 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

شناسه معامله اختیاری برای آگهی پوششی.

درستی‌سنجی

درستی‌سنجی حاوی اطلاعاتی برای Open Measurement است که اندازه‌گیری درستی‌سنجی و رؤیت‌پذیری شخص ثالث را تسهیل می‌کند. درحال‌حاضر، فقط منابع جاوا اسکریپت پشتیبانی می‌شود. به 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)]

فهرست منابع جاوا اسکریپت برای درستی‌سنجی.
tracking_events [object(TrackingEvent)]

فهرست رویدادهای ردیابی برای درستی‌سنجی.
parameters string

رشته‌ای مبهم به کد درستی‌سنجی راه‌اندازی ارسال شد.

منبع JavaScript

JavaScriptResource حاوی اطلاعاتی برای درستی‌سنجی ازطریق جاوا اسکریپت است.
نمایش JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
فیلدها
script_url string

URI به بار داده جاوا اسکریپت.
api_framework string

APIFramework نام چارچوب ویدیویی است که کد درستی‌سنجی را اجرا می‌کند.
browser_optional boolean

اینکه این دستورگان می‌تواند خارج از مرورگر اجرا شود یا نه.

TrackingEvent

TrackingEvent حاوی نشانی‌های وبی است که باید توسط مشتری در شرایط خاصی پینگ شود.
نمایش JSON
{
  "event": string,
  "uri": string,
}
فیلدها
event string

نوع رویداد ردیابی.
uri string

رویداد ردیابی که باید پینگ شود.

UniversalAdID

از UniversalAdID برای ارائه شناسه یکتای طرح آگهی استفاده می‌شود که در سیستم‌های آگهی حفظ می‌شود.
نمایش JSON
{
  "id_value": string,
  "id_registry": string,
}
فیلدها
id_value string

شناسه آگهی جهانی طرح‌آگهی انتخاب‌شده برای آگهی.
id_registry string

رشته‌ای که برای شناسایی نشانی وب وب‌سایت ثبت استفاده می‌شود که در آن «شناسه آگهی جهانی» طرح آگهی انتخاب‌شده فهرست‌بندی شده است.

همراه

Companion حاوی اطلاعاتی برای آگهی‌های همراه است که ممکن است همراه با آگهی نمایش داده شوند.
نمایش 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، این نشانی وب برای بارگیری و نمایش خواهد بود. برای آگهی‌های همراه 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

نشانی وب طرح‌آگهی تعاملی.
type string

نوع MIME فایل ارائه‌شده به‌عنوان منبع.
variable_duration boolean

اینکه آیا این طرح‌آگهی می‌تواند درخواست تمدید مدت‌زمان کند یا نه.
ad_parameters string

مقدار گره <AdParameters> در VAST.