DAI API הוא בגרסת בטא ויכול להיות שלא יהיה זמין ברשת שלכם. לקבלת מידע נוסף יש לפנות למנהל החשבון. מומלץ להשתמש ב-IMA SDK בפלטפורמות שבהן הוא זמין.

דף זה תורגם על ידי Cloud Translation API.

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

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

שירות: dai.google.com

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

שיטה: stream

Methods

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 למקור התוכן ולמזהה הסרטון שצוינו.

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

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

ייצוג ב-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": [], }

ייצוג ב-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, }

ייצוג ב-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)], }

ייצוג ב-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.

VOD API להטמעת מודעות דינמיות קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

שירות: dai.google.com

שיטה: stream

בקשת HTTP

כותרת הבקשה

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

גוף הבקשה

גוף התשובה

Open Measurement

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

בקשת HTTP

גוף התשובה

מזהי מדיה של מודעות (HLS)

מזהי מדיה של מודעות (DASH)

נתוני התגובה

מקור נתונים

AppleTV

AdBreak

מודעה

אירוע

Subtitle

SkipMetadata

סמל

ClickData

FallbackImage

Wrapper

אימות

JavaScriptResource

TrackingEvent

UniversalAdID

Companion

InteractiveFile

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