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

ה-API של הטמעת מודעות דינמיות (DAI) מאפשר לכם לבקש 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 מכיל מידע לצורך אימות מדידה פתוחה Verifications. השדה הזה מכיל לפחות שדה אחד רכיבי Verification שמפרטים את המשאבים והמטא-נתונים שנדרשים להפעלה קוד מדידה של צד שלישי כדי לאמת את הפעלת הקריאייטיב. רק יש תמיכה ב-JavaScriptResource. מידע נוסף זמין במאמר IAB Tech Lab מפרט VAST 4.1.

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

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

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

(DEPRECATED) כתובת URL רבת-משתנים של HLS. שימוש ב-'stream_manifest' במקום זאת.
media_verification_url string

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

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

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

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

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

אימות

האימות מכיל מידע עבור מדידה פתוחה, שמאפשר מדידת הניראות והאימות על ידי צד שלישי. בשלב זה, יש תמיכה רק במשאבי 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 למטען ייעודי (payload) של JavaScript.
api_framework string

APIFramework הוא השם של מסגרת הסרטון שמבצעת את בקוד האימות.
browser_optional boolean

האם ניתן להריץ את הסקריפט הזה מחוץ בדפדפן.

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.