API خطی درج آگهی پویا

API درج آگهی پویا به شما امکان می‌دهد تا جریان‌های خطی (LIVE) 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

کلید API ارائه شده هنگام ایجاد جریان، باید برای شبکه ناشر معتبر باشد.

به جای ارائه آن در بدنه درخواست، کلید API را می توان در هدر مجوز HTTP با فرمت زیر ارسال کرد:

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

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

مولفه های
assetKey string

شناسه رویداد جریان.
توجه: کلید دارایی جریان یک شناسه است که در رابط کاربری Ad Manager نیز یافت می‌شود.

درخواست بدن

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

مولفه های
dai-ssb اختیاری

برای ایجاد جریانی از سمت سرور، روی true تنظیم کنید. پیش فرض ها به false . ردیابی جریان پیش‌فرض توسط مشتری آغاز می‌شود و در سمت سرور پینگ می‌شود.

پارامترهای هدف DFP اختیاری پارامترهای هدف گیری اضافی
نادیده گرفتن پارامترهای جریان اختیاری مقادیر پیش‌فرض پارامتر ایجاد جریان را لغو کنید.
احراز هویت HMAC اختیاری با استفاده از توکن مبتنی بر HMAC احراز هویت.

بدن پاسخگو

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

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

API DAI حاوی اطلاعاتی برای تأیید اندازه‌گیری باز در قسمت Verifications است. این فیلد حاوی یک یا چند عنصر Verification است که منابع و ابرداده های مورد نیاز برای اجرای کد اندازه گیری شخص ثالث را به منظور تأیید پخش خلاق فهرست می کند. فقط JavaScriptResource پشتیبانی می شود. برای اطلاعات بیشتر، لطفاً به آزمایشگاه فناوری IAB و مشخصات VAST 4.1 مراجعه کنید.

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

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

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

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

API را از یک رویداد تأیید رسانه مطلع می کند.

درخواست 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)

شناسه‌های رسانه تبلیغاتی با استفاده از کلید TXXX که برای قاب‌های «اطلاعات متنی تعریف‌شده توسط کاربر» رزرو شده، در فراداده‌های زمان‌بندی شده HLS کدگذاری می‌شوند. محتویات قاب رمزگذاری نشده خواهد بود و همیشه با متن "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 استفاده می‌شود.

داده های پاسخ

جریان

Stream برای ارائه فهرستی از منابع برای یک جریان تازه ایجاد شده در قالب 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

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

انواع وقفه های معتبر عبارتند از: pre، mid و post.
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

bool اختیاری که نشان می دهد ورودی فعلی تخته سنگ است.
icons [object(Icon)]

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

لیستی از 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

Fallback Image

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

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

تایید

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

یک رشته مات به کد تأیید بوت استرپ ارسال شد.

JavaScriptResource

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

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

APIFramework نام چارچوب ویدیویی است که کد تأیید را اعمال می کند.
browser_optional boolean

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

TrackingEvent

TrackingEvent حاوی 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

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

همراه و همدم

Companion حاوی اطلاعاتی برای تبلیغات همراه است که ممکن است همراه با آگهی نمایش داده شود.
نمایندگی 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 اگر همراهی از نوع static باشد.
height int32

ارتفاع بر حسب پیکسل این همراه.
width int32

عرض بر حسب پیکسل این همراه.
resource string

برای همراهان استاتیک و iframe این نشانی اینترنتی است که باید بارگیری و نمایش داده شود. برای همراهان HTML، این قطعه HTML است که باید به عنوان همراه نشان داده شود.
type string

نوع این همراه. می تواند ثابت، iframe یا HTML باشد.

فایل تعاملی

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.