API زنده ارائه غلاف درج آگهی پویا

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 pod ارائه جلسه پخش زنده را ثبت می کند.

درخواست HTTP

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

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

مولفه های
network_code string

کد شبکه Google Ad Manager ناشر.

custom_asset_key string

شناسه سفارشی مربوط به این رویداد در Google Ad Manager است.

درخواست بدن

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

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

بدن پاسخگو

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

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

API DAI حاوی اطلاعاتی برای تأیید اندازه‌گیری باز در قسمت 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 Ad Manager ناشر.

custom_asset_key string

شناسه سفارشی مربوط به این رویداد در Google Ad Manager است.

pod_id integer

شناسه عددی برای وقفه تبلیغاتی فعلی. شناسه‌های غلاف آگهی به صورت تدریجی برای هر رویداد اختصاص داده می‌شوند که از ۱ شروع می‌شود.

profile_name string

نام نمایه رمزگذاری Google Ad Manager DAI درخواستی . نمایه رمزگذاری باید یکی از نمایه های رمزگذاری پیکربندی شده برای رویداد انتخاب شده باشد.

segment_number integer

نمایه بخش درخواستی در غلاف تبلیغات فعلی که از صفر شروع می شود.

segment_format string

پسوند فایل مرتبط با قالب بخش درخواستی. پسوندهای پذیرفته شده عبارتند از: ts , mp4 , vtt , aac , ac3 یا eac3 .

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

مولفه های
stream_id ضروری string

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

sd required 1 integer

مدت زمان بخش درخواستی، بر حسب میلی ثانیه.

so اختیاری

افست بخش درخواستی در غلاف آگهی، در میلی ثانیه. اگر پارامتر so حذف کنید، با ضرب مدت زمان بخش در شماره بخش محاسبه می شود.

pd مورد نیاز 2 integer

مدت زمان غلاف آگهی، بر حسب میلی ثانیه.

auth-token ضروری string

یک نشانه HMAC امضا شده و کدگذاری شده با URL برای غلاف تبلیغات فعلی.

last اختیاری boolean

آخرین بخش در وقفه تبلیغاتی را نشان می دهد. این پارامتر را برای تمام بخش های دیگر حذف کنید.

scte35 اختیاری string

سیگنال SCTE-35 با کد Base64 برای این استراحت تبلیغاتی.

cust_params اختیاری string

مجموعه‌ای از جفت‌های کلید-مقدار که برای هدف‌یابی کمپین Ad Manager استفاده می‌شود. این جفت ها باید به عنوان یک رشته پرس و جو کدگذاری شده با آدرس اینترنتی نمایش داده شوند.

مثال:
مولفه های
  • بخش = 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

از Google Ad Manager یک الگوی دوره DASH درخواست می کند. این الگو حاوی ماکروهایی است که باید آنها را با پارامترهای جریان خود پر کنید. پس از پر شدن این ماکروها، الگو به دوره وقفه تبلیغاتی شما تبدیل می شود و می توان آن را در مانیفست 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 Ad Manager ناشر.

custom_asset_key string

شناسه سفارشی مربوط به این رویداد در Google Ad Manager است.

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

مولفه های
stream_id ضروری string

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

بدن پاسخگو

در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی یک شی جدید PodTemplateResponse است.

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

پس از مواجهه با شناسه رسانه تبلیغاتی در حین پخش، بلافاصله با استفاده از 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 یا 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 استفاده می‌شود.

داده های پاسخ

جریان

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

شناسه جریان GAM.
media_verification_url string

نشانی وب تأیید رسانه که به عنوان نقطه پایانی پایه برای ردیابی رویدادهای پخش استفاده می‌شود.
metadata_url string

URL فراداده برای نظرسنجی اطلاعات دوره ای در مورد رویدادهای تبلیغات جریانی آتی استفاده می شود.
session_update_url string

نشانی وب به‌روزرسانی جلسه برای به‌روزرسانی پارامترهای هدف برای این جریان استفاده می‌شود. مقادیر اصلی برای پارامترهای هدف گیری در طول درخواست ایجاد جریان اولیه گرفته می شود.
heartbeat_url string

URL ضربان قلب، که برای زنده نگه داشتن جریان beaconing سمت سرور استفاده می‌شود، باید هر {PollingFrequency} ثانیه یک بار پینگ شود. پر شده برای جریان‌های نشان‌دهنده سمت سرور.
polling_frequency number

فرکانس نظرسنجی، در ثانیه، هنگام درخواست metadata_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 با 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) که باید در حین پخش آگهی نمایش داده شود.

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

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

نوع رویداد ردیابی
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 اگر همراهی از نوع static باشد.
height int32

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

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

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

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

شناسه اسلات برای این همراه.
api_framework string

چارچوب API برای این همراه.
tracking_events [object(TrackingEvent)]

لیست رویدادهای ردیابی برای این همراه.

فایل تعاملی

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.