ה-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 מזהה האירוע של השידור. |
גוף הבקשה
גוף הבקשה הוא מסוג application/x-www-form-urlencoded
ומכיל את הפרמטרים הבאים:
פרמטרים | ||
---|---|---|
dai-ssb |
אופציונלי | יש להגדיר את הערך |
פרמטרים של טירגוט ב-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. |