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

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

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

פרמטרים
content-source string

מזהה מערכת ניהול התוכן של מקור הנתונים.

video-id string

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

גוף הבקשה

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

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

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

גוף התשובה

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

פתיחת המדידה

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

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

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

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

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)]

רשימה של wrappers. לא יופיע אם השדה ריק.
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

נתוני הקליק מכילים מידע על קליק על סמל.
ייצוג 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

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

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

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

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

אימות

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

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

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.