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

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

גוף התשובה

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

פתיחת המדידה

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

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

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

הבקשות לנקודת הקצה 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

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

כתובת ה-URL של המניפסט של השידור, משמשת לאחזור הפלייליסט רב-המשתנים ב-HLS או ב-MPD ב-DASH.
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)]

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

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