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

ה-API של הטמעת מודעות דינמיות מאפשר לבקש שידורים לינאריים (LIVE) של 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' בפורמט הבא:

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

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

פרמטרים
assetKey string

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

גוף הבקשה

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

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

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

גוף התשובה

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

פתיחת המדידה

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

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

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

הבקשות שנשלחות לנקודת הקצה (endpoint) 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, ונשמרים למסגרות מסוג "user-defined text information". תוכן הפריים לא יהיה מוצפן ותמיד יתחיל בטקסט "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. לאחר מכן, עוברים בין התגים ומוצאים את הרשומה הראשונה ששמה הוא קידומת של מזהה המדיה של המודעה שנמצאה ב-Video Stream. לדוגמה, יכול להיות שיש לכם מזהה מדיה של מודעה שנראה כך:

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 של פלייליסט רב-משתנים(הוצאה משימוש). במקומו צריך להשתמש ב-'stream_manifest'.
media_verification_url string

כתובת ה-URL לאימות במדיה שמשמשת כנקודת קצה בסיסית למעקב אחרי אירועי הפעלה.
metadata_url string

כתובת URL של מטא-נתונים שמשמשת לבדיקת מידע תקופתי לגבי אירועים קרובים של מודעות בסטרימינג.
session_update_url string

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

תדירות הדגימה, בשניות, כשמבקשים מטא-נתונים מ-metadata_url או פעימות_כתובת 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

רשימה אופציונלית של כל צומתי <תוסף> ב-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.
ייצוג 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.