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