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

Dynamic Ad Insertion API מאפשר לבקש ולעקוב אחרי שידורי וידאו על פי דרישה (VOD) עם הטמעת מודעות דינמיות. יש תמיכה בשידורים מסוג HLS ו-DASH.

שירות: dai.google.com

הנתיב של השיטה stream הוא יחסי ל-https://dai.google.com

שיטה: stream

Methods
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: DCLKDAI key="<api-key>"

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

פרמטרים
content-source string

מזהה ה-CMS של מקור הנתונים.

video-id string

מזהה הסרטון של השידור.

גוף הבקשה

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

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

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

גוף התשובה

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

Open Measurement

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

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

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

בקשות לנקודת הקצה media verification הן חד-פעמיות.

Methods
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 של Scheme ID‏ urn:google:dai:2018. הם יכללו אירועים עם המאפיין messageData שמכיל מזהה מדיה של מודעה שמתחיל ב-“google_”. צריך לצרף את כל התוכן של המאפיין messageData אל media_verification_url בכל בקשה לאימות מודעה.

נתוני התגובה

מקור נתונים

הפונקציה Stream משמשת להצגה של רשימה של כל המשאבים של שידור חדש שנוצר בפורמט 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', שמופיע בתגובה כשיוצרים שידור של איתותים בצד השרת.
media_verification_url string

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

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

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

AppleTV

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

כתובת ה-URL של המודעות המעבריות.

AdBreak

האירוע AdBreak מתאר הפסקה אחת למודעה בשידור. הוא מכיל מיקום, משך זמן, סוג (אמצע/לפני/אחרי) ורשימת מודעות.
ייצוג ב-JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
שדות
type string

סוגים חוקיים של הפסקות: mid,‏ pre ו-post.
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)]

רשימת Wrappers. השדה הזה לא מופיע אם הוא ריק.
events [object(Event)]

רשימה של האירועים במודעה.
verifications [object(Verification)]

רשומות אופציונליות לאימות של Open Measurement, שמפרטות את המשאבים והמטא-נתונים הנדרשים להרצת קוד מדידה של צד שלישי כדי לאמת את ההפעלה של הקריאייטיב.
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

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

Subtitle

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

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

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

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

כתובת URL אופציונלית לקובץ ה-sidecar של WebVTT.

SkipMetadata

הפרמטר SkipMetadata מספק מידע שדרוש ללקוחות כדי לטפל באירועי דילוג על מודעות שניתן לדלג עליהן.
ייצוג ב-JSON
{
  "offset": number,
  "tracking_url": string,
}
שדות
offset number

השינוי מציין את משך הזמן בשניות שנגן הווידאו צריך להמתין אחרי תחילת המודעה כדי להציג את לחצן הדילוג. המערכת תשמיט את השדה אם לא יצוין ב-VAST.
tracking_url string

TrackingURL מכילה כתובת URL שצריך לשלוח אליה הודעות ping באירוע הדילוג.

סמל

הסמל מכיל מידע על סמל 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

ה-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

מזהה עסקה אופציונלי למודעה העליונה.

אימות

האימות מכיל מידע ל-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

מחרוזת אטומה שמועברת לקוד האימות של Bootstrap.

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

האירוע TrackingEvent מכיל כתובות URL שעל הלקוח לשלוח אליהן הודעות ping במצבים מסוימים.
ייצוג ב-JSON
{
  "event": string,
  "uri": string,
}
שדות
event string

סוג אירוע המעקב.
uri string

אירוע המעקב שעבורו יישלח ה-ping.

UniversalAdID

UniversalAdID משמש לספק מזהה קריאייטיב ייחודי שנשמר במערכות הפרסום השונות.
ייצוג ב-JSON
{
  "id_value": string,
  "id_registry": string,
}
שדות
id_value string

מזהה המודעה האוניברסלי של הקריאייטיב שנבחר עבור המודעה.
id_registry string

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

Companion

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, זו תהיה כתובת ה-URL שתישאר טעונה ותוצג. במודעות נלוות מסוג HTML, זהו קטע ה-HTML שצריך להופיע כמודעה הנלווית.
type string

הסוג של המלווה הזה. הוא יכול להיות סטטי, iframe או HTML.
ad_slot_id string

מזהה השקע של המלווה הזה.
api_framework string

מסגרת ה-API של התוסף הזה.
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

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