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

ה-API של הטמעת מודעות דינמיות (DAI) מאפשר לכם לבקש DAI ולעקוב אחריהן וידאו על פי דרישה (VOD). שידורי HLS ו-DASH נתמכים.

שירות: dai.google.com

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

שיטה: זרם

שיטות
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

יוצר שידור DAI מסוג HLS עבור מקור התוכן ומזהה הסרטון הנתונים.

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

גוף התשובה

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

פתיחת המדידה

השדה Verifications מכיל את המידע לגבי הערך 'פתיחה'. אימות מדידה עבור שידורים עם משׂואת רשת (beacon) בצד השרת. הרכיב Verifications מכיל לפחות רכיב אחד של Verification שמציג את רשימת המשאבים ואת המטא-נתונים הנדרשים כדי לאמת את הפעלת הקריאייטיב באמצעות קוד מדידה של צד שלישי. יש תמיכה רק ב-JavaScriptResource. לקבלת מידע נוסף, מידע נוסף זמין ב-IAB Tech Lab ומפרט VAST 4.1.

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

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

הבקשות שנשלחות לנקודת הקצה (endpoint) 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' שנמצא בתשובה יצירת סטרימינג באמצעות אות (beaconing) בצד השרת.
media_verification_url string

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

מידע אופציונלי שספציפי למכשירי AppleTV. בפרוטוקול 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),
  "skip_metadata": object(SkipMetadata),
}
שדות
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) אופציונלי שצריך להציג במהלך הפעלת המודעה.
skip_metadata object(SkipMetadata)

מטא-נתונים אופציונליים למודעות שניתנות לדילוג. אם הוא מוגדר, המאפיין הזה מציין את המודעה ניתן לדלג עליה, וכוללת הוראות לטיפול בממשק המשתמש לדילוג ואירוע מעקב.

אירוע

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

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

סוג האירוע.

Subtitle

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

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

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

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

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

SkipMetadata

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

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

כתובת URL למעקב מכילה כתובת URL שצריך לבצע פינג לגבי אירוע הדילוג.

סמל

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

מזהה המודעה שמשמש את מודעת ה-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

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

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

מעקב אחר אירוע מכיל כתובות 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.