ממשק API לינארי להטמעת מודעות דינמיות

באמצעות ה-Dynamic Ad Insertion API אפשר לבקש שידורים לינאריים (בשידור חי) של DAI ולעקוב אחריהם.

שירות: dai.google.com

כל מזהי ה-URI הבאים הם יחסיים ל-https://dai.google.com

שיטה: שידור

שיטות
stream POST /linear/v1/hls/event/{assetKey}/stream

יוצר שידור DAI למזהה האירוע הנתון.

בקשת HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

כותרת הבקשה

פרמטרים
api‑key string

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

במקום לספק את המפתח בגוף הבקשה, ניתן להעביר את מפתח ה-API בכותרת 'הרשאת HTTP' בפורמט הבא:

Authorization: DCLKDAI key="<api-key>"

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

פרמטרים
assetKey string

מזהה האירוע של השידור.
הערה: מפתח נכס השידור הוא מזהה שנמצא גם ב ממשק המשתמש של Ad Manager.

גוף הבקשה

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

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

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

גוף התגובה

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

מדידה פתוחה

DAI API מכיל מידע על אימות ב-Open Measurement בשדה Verifications. בשדה הזה יש רכיב Verification אחד או יותר שמפרטים את המשאבים והמטא-נתונים שנדרשים להפעלת קוד מדידה של צד שלישי לצורך אימות ההפעלה של נכסי הקריאייטיב. יש תמיכה רק ב-JavaScriptResource. למידע נוסף, ראו IAB Tech Lab ומפרט VAST 4.1.

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

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

בקשות לנקודת הקצה media verification הן אידמפוטנטיות.

שיטות
media verification GET /{media_verification_url}/{ad_media_id}

שולח התראה ל-API על אירוע אימות מדיה.

בקשת HTTP

GET https://{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_".

יש לצרף את כל תוכן הטקסט של המסגרת לכתובת ה-URL לאימות המודעה, לפני שליחת כל בקשת אימות למודעה.

שיטה: מטא-נתונים

נקודת הקצה של המטא-נתונים ב-metadata_url מחזירה מידע ששימש לבניית ממשק המשתמש של המודעה. נקודת הקצה למטא-נתונים לא זמינה לשידורים של איתות Bluetooth מצד השרת, שבהם השרת אחראי להתחיל אימות של מדיה של מודעה.

שיטות
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

אחזור פרטי מטא נתונים של מודעות.

בקשת HTTP

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

גוף התגובה

אם הפעולה בוצעה ללא שגיאות, התשובה תחזיר מופע של PodMetadata.

עבודה עם מטא נתונים

למטא-נתונים יש שלושה קטעים נפרדים: tags, ads ומודעה breaks. נקודת הכניסה לנתונים היא הקטע tags. משם, חוזרים על השלבים בין התגים ומוצאים את הרשומה הראשונה ששמה הוא התחילית של מזהה המדיה של המודעה שנמצא בשידור הווידאו. לדוגמה, יכול להיות שיש לכם מזהה מדיה של מודעה שנראה כך:

google_1234567890

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

נתוני תגובה

נחל

מקור הנתונים משמש לעיבוד רשימת משאבים של שידור חדש שנוצר בפורמט JSON.
ייצוג JSON
{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}
שדות
stream_id string

מזהה מקור נתונים.
stream_manifest string

המניפסט של השידור, שתואם לפלייליסט הראשי ב-HLS או ב-MPD ב-DASH. זהו השדה היחיד חוץ מ-stream_id שמופיע בתגובה כשיוצרים זרם איתות Bluetooth מצד השרת.
hls_master_playlist string

(הוצאת כתובת ה-URL של הפלייליסט הראשי ב-HLS (הוצא משימוש). במקומו צריך להשתמש ב-'stream_manifest'.
media_verification_url string

כתובת URL לאימות מדיה.
metadata_url string

כתובת ה-URL של המטא-נתונים של המדיה במודעה.
session_update_url string

כתובת URL לעדכון סשן.
polling_frequency number

תדירות מומלצת של סקרים לגבי כתובות URL של מטא-נתונים, בשניות.

PodMetadata

PodMetadata מכיל פרטי מטא-נתונים של מודעות, הפסקות למודעות ותגים של מזהה מדיה.
ייצוג JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
שדות
tags map[string, object(TagSegment)]

מפה של קטעי התג שנוספו לאינדקס לפי קידומת התג.
ads map[string, object(Ad)]

מפה של מודעות שנוספו לאינדקס לפי מזהה המודעה.
ad_breaks map[string, object(AdBreak)]

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

TagSegment

TagSegment מכיל הפניה למודעה, הפסקה למודעה וסוג האירוע. אין לבצע פינג ל-TagSegment עם type="progress" לנקודת הקצה לאימות המדיה של המודעה.
ייצוג JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
שדות
ad string

מזהה המודעה של התג הזה.
ad_break_id string

מזהה ההפסקה למודעה של התג הזה.
type string

סוג האירוע של התג הזה.

AdBreak

AdBreak מתאר הפסקה יחידה למודעה במהלך השידור. היא כוללת משך זמן, סוג (mid/pre/post) ואת מספר המודעות.
ייצוג JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
שדות
type string

סוגי ההפסקות החוקיים הם: לפני, באמצע ואחרי.
duration number

משך הזמן הכולל למודעה עבור ההפסקה הזו למודעות, בשניות.
expected_duration number

משך הזמן הצפוי של ההפסקה למודעות (בשניות), כולל כל המודעות וכל שקופית חוסמת.
ads number

מספר המודעות בהפסקה למודעות.
המודעה מתארת מודעה בזרם.
ייצוג JSON
{
  "ad_break_id": string,
  "position": 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,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
שדות
ad_break_id string

המזהה של ההפסקה למודעה של המודעה הזו.
position number

המיקום של המודעה הזו בהפסקה למודעה, החל מ-1.
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 אופציונלית לקליקים.
click_tracking_urls string

כתובות URL אופציונליות למעקב אחר קליקים.
verifications [object(Verification)]

רשומות אופציונליות של אימות המדידה, שבהן מפורטות המשאבים והמטא-נתונים הנדרשים להפעלת קוד מדידה של צד שלישי לצורך אימות ההפעלה של נכסי הקריאייטיב.
slate boolean

בול אופציונלי שמציין שהערך הנוכחי הוא צפחה.
icons [object(Icon)]

רשימת סמלים, אם הם ריקים.
wrappers [object(Wrapper)]

רשימת קובצי ראפ, הושמטה אם היא ריקה.
universal_ad_id object(UniversalAdID)

מזהה מודעה אוניברסלי אופציונלי.
extensions string

רשימה אופציונלית של כל הצמתים של <Extension> ב-VAST.
companions [object(Companion)]

מודעות נלוות אופציונליות שייתכן שיוצגו יחד עם המודעה הזו.
interactive_file object(InteractiveFile)

קריאייטיב אינטראקטיבי (SIMID) אופציונלי שצריך להציג במהלך הפעלת המודעה.

סמל

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