ממשק ה-API של הטמעת מודעות דינמיות (DAI) מאפשר לכם לבקש שידורי וידאו על פי דרישה (VOD) של DAI ולעקוב אחריהם. שידורי HLS ו-DASH נתמכים.
שירות: dai.google.com
הנתיב של השיטה stream
יחסי ל-https://dai.google.com
שיטה: זרם
שיטות | |
---|---|
stream |
POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
יוצר שידור DAI מסוג HLS עבור מקור התוכן ומזהה הסרטון הנתונים.
יוצר זרם 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 |
אופציונלי | יש להגדיר את הערך |
פרמטרים של טירגוט ב-DFP | אופציונלי | פרמטרים נוספים של טירגוט. |
שינוי פרמטרים של מקור נתונים | אופציונלי | שינוי ערכי ברירת המחדל של פרמטר ליצירת שידור |
אימות HMAC | אופציונלי | אימות באמצעות אסימון מבוסס HMAC. |
גוף התשובה
אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל Stream
חדש. בשידורים עם משׂואת רשת (beacon) בצד השרת, השדה Stream
מכיל רק את השדות stream_id
ו-stream_manifest
.
פתיחת המדידה
השדה Verifications
מכיל מידע לגבי תהליך האימות של Open Measurement עבור שידורים ללא איתות Bluetooth בצד השרת.
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' שמופיע בתגובה כשיוצרים שידור סטרימינג של איתות 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)] רשימה של דפי גרפיקה. הושמט אם השדה ריק. |
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 לקובץ הצד הצדדי של TicketML, ומאפיין 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.ייצוג 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 מחרוזת אטומה שמועברת לקוד אימות מסוג bootrap. |
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 סוג אירוע המעקב. |
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. |