VOD API להטמעת מודעות דינמיות

באמצעות ה-Dynamic Ad Insertion 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, שמתקבל כשיוצרים שידור חייב להיות תואם לרשת של בעל התוכן הדיגיטלי.

במקום להזין אותו בגוף הבקשה, אפשר להעביר את מפתח ה-API בכותרת HTTP Authorization בפורמט הבא:

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

פרמטרים של נתיב

פרמטרים
content-source string

מזהה מערכת ניהול התוכן (CMS) של השידור.

video-id string

מזהה הווידאו של השידור.

גוף הבקשה

גוף הבקשה הוא מסוג application/x-www-form-urlencoded ומכיל את הפרמטרים הבאים:

פרמטרים
dai-ssb אופציונלי

צריך להגדיר את הערך true כדי ליצור זרם איתות Bluetooth מצד השרת. ברירת המחדל היא false. המעקב של עדכוני ברירת המחדל מתבצע ביוזמת הלקוח ומתבצעת ping בצד השרת.
פרמטרים של טירגוט ב-AdX אופציונלי פרמטרים נוספים של טירגוט.
שינוי פרמטרים של השידור אופציונלי שינוי ערכי ברירת המחדל של פרמטר ליצירת מקור נתונים.
אימות HMAC אופציונלי אימות באמצעות אסימון שמבוסס על HMAC.

גוף התגובה

אם הביצוע יהיה תקין, גוף התגובה יכלול ערך של Stream חדש. בשידורים של איתות Bluetooth מצד השרת, Stream מכיל רק את השדות stream_id ו-stream_manifest.

מדידה פתוחה

השדה Verifications מכיל מידע על אימות במדידה פתוחה עבור שידורים של איתות Bluetooth שלא בצד השרת. Verifications מכיל לפחות רכיב Verification אחד עם רשימת המשאבים והמטא-נתונים שנדרשים כדי לאמת את ההפעלה של נכסי הקריאייטיב באמצעות קוד מדידה של צד שלישי. יש תמיכה רק ב-JavaScriptResource. למידע נוסף, ראו IAB Tech Lab ומפרט VAST 4.1.

שיטה: אימות מדיה

ברגע שנוצר מזהה מדיה של מודעה במהלך ההפעלה, צריך לשלוח מיד בקשה עם media_verification_url מנקודת הקצה stream. הערך media_verification_url הוא נתיב מוחלט. אין צורך בבקשות לאימות מדיה לשידורים של איתות Bluetooth בצד השרת, במקרים שבהם השרת מפעיל אימות מדיה.

בקשות לנקודת הקצה media verification הן אידמפוטנטיות.

שיטות
media verification GET {media_verification_url}/{ad_media_id}

שולח התראה ל-API על אירוע אימות מדיה.

בקשת HTTP

GET {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_".

יש לצרף את כל תוכן הטקסט של המסגרת לערך 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

(הוצאת כתובת ה-URL של הפלייליסט הראשי ב-HLS (הוצא משימוש). שימוש ב-stream_manifest. HLS בלבד.
stream_manifest string

המניפסט של השידור. תואם לפלייליסט הראשי ב-HLS ול-MPD ב-DASH. זהו השדה היחיד מלבד "stream_id" שמוצג בתגובה כשיוצרים זרם העברת נתונים (beacon) בצד השרת.
media_verification_url string

כתובת URL לאימות מדיה.
apple_tv object(AppleTV)

מידע אופציונלי ספציפי למכשירי Apple TV. HLS בלבד.
ad_breaks [object(AdBreak)]

רשימה של הפסקות למודעות. לא יופיע אם השדה ריק.

AppleTV

Apple TV מכיל מידע ספציפי למכשירי Apple TV.
ייצוג JSON
{
  "interstitials_url": string,
}
שדות
interstitials_url string

כתובת URL של מודעות מעברון.

AdBreak

AdBreak מתאר הפסקה יחידה למודעה במהלך השידור. היא כוללת מיקום, משך זמן, סוג (mid/pre/post) ורשימה של מודעות.
ייצוג 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),
}
שדות
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

כתובת URL אופציונלית לקליקים.
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) אופציונלי שצריך להציג במהלך הפעלת המודעה.

אירוע

האירוע כולל סוג אירוע וזמן ההצגה שלו.
ייצוג JSON
{
  "time": number,
  "type": string,
}
שדות
time number

שעת ההצגה של האירוע הזה.
type string

סוג האירוע הזה.

Subtitle

'כתוביות' מתארות רצועת כתוביות צדדית לשידור הווידאו. היא שומרת שני פורמטים של כתוביות: TTML ו-WebVTT. המאפיין TTMLPath מכיל את כתובת ה-URL של קובץ העזר של TTML, ומאפיין WebVTTPath מכיל באופן דומה כתובת URL לקובץ הצדדי של WebVTT.
ייצוג JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
שדות
language string

קוד שפה, כמו 'en' או 'de'.
language_name string

שם תיאורי של השפה. היא מבדילה בין קבוצת הכתוביות הספציפית אם יש כמה קבוצות לאותה שפה
ttml string

כתובת URL אופציונלית לקובץ הצד של TTML.
webvtt string

כתובת URL אופציונלית לקובץ העזר של WebVTT.

סמל

הסמל מכיל מידע על סמל 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 מסוג 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 מכיל מידע על מודעת wrapper. הוא לא כולל מזהה עסקה אם הוא לא קיים.
ייצוג JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
שדות
system string

מזהה מערכת המודעות.
ad_id string

מזהה המודעה המשמש למודעת ה-wrapper.
creative_id string

מזהה הקריאייטיב משמש למודעת ה-wrapper.
creative_ad_id string

מזהה מודעת הקריאייטיב המשמש ליצירת מודעת ה-wrapper.
deal_id string

מזהה מבצע אופציונלי למודעת wrapper.

אימות

האימות מכיל מידע ל-Open Measurement, שמאפשר מדידת ניראות ואימות על ידי צד שלישי. בשלב זה יש תמיכה רק במשאבי 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 למטען ייעודי (payload) של JavaScript.
api_framework string

APIFramework הוא השם של ה-framework של סרטון האימות שמפעיל את קוד האימות.
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

מחרוזת שמשמשת לזיהוי כתובת ה-URL של אתר המרשם שבו נכלל הקטלוג של מזהה הפרסום האוניברסלי של הקריאייטיב שנבחר.

נלווית

מודעה נלווית מכילה מידע למודעות נלוות שניתן להציג יחד עם המודעה.
ייצוג 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, אם זוהי מודעה נלווית מסוג סטטי.
height int32

הגובה בפיקסלים של המודעה הנלווית הזו.
width int32

הרוחב בפיקסלים של המודעה הנלווית הזו.
resource string

למודעות נלוות סטטיות ו-iframe, זו תהיה כתובת ה-URL לטעינה ולהצגה. בכלי נלווה של HTML, זה יהיה קטע הקוד של ה-HTML שצריך להציג בתור המודעה הנלווית.
type string

הסוג של המודעה הנלווית. אפשר להזין טקסט סטטי, iframe או HTML.

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

הערך של הצומת <AdParameters> ב-VAST.