Google DAI API מאפשר לכם להטמיע סטרימינג עם DAI של Google בסביבות שבהן אין תמיכה בהטמעה של IMA SDK. מומלץ להמשיך להשתמש ב-IMA בפלטפורמות שבהן יש תמיכה ב-IMA SDK.
מומלץ להשתמש ב-DAI API בפלטפורמות הבאות:
- טלוויזיה חכמה של Samsung (Tizen)
- טלוויזיה של LG
- HbbTV
- Xbox (אפליקציות JavaScript)
- KaiOS
ה-API תומך ביכולות הבסיסיות שמסופקות על ידי IMA DAI SDK. לשאלות ספציפיות לגבי תאימות או תכונות נתמכות, אפשר לפנות לנציג שמטפל בחשבון Google שלכם.
הטמעה של DAI API בשידורים חיים
ה-API של DAI תומך בשידורים ליניאריים (בשידור חי) באמצעות הפרוטוקולים HLS ו-DASH. השלבים שמתוארים במדריך הזה רלוונטיים לשני הפרוטוקולים.
כדי לשלב את ה-API באפליקציה שלכם לשידורים חיים, צריך לבצע את השלבים הבאים:
1. בקשה לשידור
כדי לבקש שידור חי מ-DAI API, שולחים קריאת POST לנקודת הקצה של השידור. תגובת ה-JSON מכילה את מניפסט הסטרימינג, וגם את נקודות הקצה והערכים המשויכים של DAI API.
גוף בקשה לדוגמה
https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream
{
"key1" : "value1",
"stream_parameter1" : "value2"
}
דוגמה לגוף התגובה
{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}
תגובה עם שגיאה
במקרה של שגיאות, מוחזרים קודי שגיאה סטנדרטיים של HTTP ללא גוף תגובת JSON.
מנתחים את תגובת ה-JSON ומאחסנים את הערכים הבאים:
- stream_id
- אפשר להשתמש בערך הזה כדי לזהות את הזרם שמוחזר.
- stream_manifest
- כתובת ה-URL הזו מועברת לנגן המדיה שלכם להפעלת הסטרימינג.
- media_verification_url
- כתובת ה-URL הזו היא נקודת הקצה הבסיסית למעקב אחרי אירועי הפעלה.
- metadata_url
- כתובת ה-URL הזו משמשת לשליחת בקשות למידע תקופתי על אירועים קרובים בשידור חי.
- session_update_url
- כתובת ה-URL הזו משמשת לעדכון פרמטרים של בקשת סטרימינג שנשלחו במהלך בקשת הסטרימינג הראשונית. שימו לב שהפרמטרים של הבקשה הזו מחליפים את כל הפרמטרים שהוגדרו לשידור הקודם.
- polling_frequency
- התדירות בשניות שבה נשלחת בקשה למטא-נתונים מעודכנים של הפסקת הפרסום מ-DAI API.
2. בדיקה אם יש מטא-נתונים חדשים של הפסקות פרסום
מגדירים טיימר לביצוע סקר לגבי מטא-נתונים חדשים של הפסקות לפרסומות בתדירות הסקר, באמצעות כתובת ה-URL של המטא-נתונים. אם לא מצוין מרווח זמן בתגובה של הסטרימינג, מרווח הזמן המומלץ שמוגדר כברירת מחדל הוא 10 שניות.
כדי לבצע אופטימיזציה של רוחב הפס:
- שליחת בקשת
GETראשונית לנקודת הקצהmetadata_url.- משמיטים את פרמטר השאילתה
delta_token. התהליך הזה מאפשר לשרת להחזיר את המטא-נתונים המלאים של חלון ה-DVR של הסטרימינג. חלון ה-DVR מכיל את מסגרת הזמן של השידור שזמינה לצופים להרצה לאחור ולהפעלה. התשובה כוללת שדה אובייקטnext_delta_token.
- משמיטים את פרמטר השאילתה
- אחסון מטא-נתונים בצד הלקוח.
- מבצעים שיחות נוספות באמצעות הערך
next_delta_tokenשמוחזר בתגובה האחרונה. כל תשובה מכילה ערךnext_delta_token. תמיד לשלוח את הערך האחרון שמתקבל. - מעדכנים את המטא-נתונים שמאוחסנים כדי למזג את השינויים ולהסיר הפסקות פרסום שהתיישנו.
אין לנסות לנתח, ליצור או לשנות את טוקן הדלתא. הפורמט של הטוקן יכול להשתנות. מאחסנים את הטוקן כפי שהוא מתקבל, ומעבירים אותו ללא שינוי בבקשה הבאה.
דוגמה לבקשה ראשונית
הבקשה הראשונית לא מקבלת פרמטרים של שאילתה ומחזירה את המטא-נתונים המלאים:
https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata
דוגמה לבקשה עוקבת
בכל בקשה עוקבת מועבר הערך next_delta_token מהתגובה הקודמת כפרמטר delta_token. התשובה מכילה את הפרטים הבאים:
- מודעות
- הפסקות למודעות
- תגים שהשרת הוסיף או עדכן מאז שהשרת הנפיק את הטוקן.
- רשימה של הפסקות פרסומות להסרה מהמטא-נתונים המאוחסנים
obsolete_ad_break_ids
השרת משמיט הפסקות לפרסומות שלא השתנו. בדוגמה הבאה אפשר לראות סקר עוקב שבו נעשה שימוש בטוקן הדלתא כדי לאחזר רק את השינויים האחרונים האלה:
https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0
אם הפעולה בוצעה בהצלחה, הפלט ייראה כך:
{
"next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
"obsolete_ad_break_ids": ["0003069407"],
"tags":{
"google_1022389921":{
"ad":"0003069408_ad1",
"ad_break_id":"0003069408",
"type":"start"
},
...
},
"ads":{
"0003069408_ad1":{
"ad_break_id":"0003069408",
"position":1,
"duration":10.01,
"title":"External - Pod Midroll 1",
...
}
},
"ad_breaks":{
"0003069408":{
"type":"mid",
"duration":30,
"expected_duration":30,
"ads":3
}
}
}
3. האזנה לאירועי ID3 ומעקב אחרי אירועי הפעלה
כדי לוודא שאירועים ספציפיים התרחשו בסטרימינג של סרטון, מבצעים את השלבים הבאים לטיפול באירועי ID3:
- מאחסנים את אירועי המדיה בתור, ושומרים כל מזהה מדיה יחד עם חותמת הזמן שלו (אם הנגן מציג אותה).
- בכל עדכון זמן מהנגן, או בתדירות מוגדרת (מומלץ 500 אלפיות השנייה), בודקים את תור אירועי המדיה כדי לראות אילו אירועים הופעלו לאחרונה על ידי השוואת חותמות הזמן של האירועים למיקום סמן ההפעלה.
- לאירועי מדיה שאישרתם שהם הופעלו, בודקים את הסוג על ידי חיפוש של מזהה המדיה בתגי ההפסקות הפרסומיות המאוחסנים. חשוב לזכור שהתגים המאוחסנים מכילים רק קידומת של מזהה המדיה, ולכן לא ניתן לבצע התאמה מדויקת.
- האפליקציה של נגן הווידאו שולחת שאילתות לכתובת ה-URL של המטא-נתונים באופן תקופתי, ולכן יכול להיות שיהיה עיכוב בין הרגע שבו נגן הווידאו נתקל בתג ID3 בסטרימינג לבין הרגע שבו המטא-נתונים המשויכים זמינים. אם לא נמצא תג ID3 בתגים המאוחסנים, התג נשמר בתור ומעובד מחדש אחרי הסקר הבא של המטא-נתונים. האירוע יישאר בתור עד שהעיבוד יסתיים.
- אחרי שמוצאים את התג במטא-נתונים, בודקים את השדה
typeבתג מול סוגי אירועי המודעות שמפורטים בקטע הבא. כדי לעקוב אחרי הפעלת הפסקה למודעה בנגן הווידאו, משתמשים באירועים עם הערךprogressמהשדהtype. אל תשלחו את האירועים האלה לנקודת הקצה (endpoint) של אימות המדיה. לכל שאר סוגי האירועים, צריך לצרף את מזהה המדיה לנקודת הקצה של אימות המדיה ולשלוח בקשתGETלמעקב אחר ההפעלה. - מסירים את אירוע המדיה מהתור.
סוגי אירועים של מודעות
לכל תג באובייקט המטא-נתונים tags יש אחד מסוגי האירועים הבאים:
| סוג אירוע | תיאור |
|---|---|
start |
מופעל בתחילת המודעה. |
firstquartile |
האירוע הזה מופעל בסוף הרבעון הראשון של המודעה. |
midpoint |
מוצגת באמצע המודעה. |
thirdquartile |
הפונקציה מופעלת בסוף הרבעון השלישי של המודעה. |
complete |
המודעה מוצגת בסוף הסרטון. |
progress |
מופעל מעת לעת במהלך הפסקה למודעות, כדי לסמן שההפסקה למודעות מתרחשת. אל תשלחו את האירועים האלה לנקודת הקצה (endpoint) של אימות המדיה. |
דוגמה לבקשה
https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921
תגובות לדוגמה
Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict
אפשר לאמת את אירועי המעקב בכלי המעקב אחר פעילות בשידור.
4. עדכון הפרמטרים של הסשן בשידור חי
יכול להיות שתרצו לשנות את הפרמטרים של הסשן אחרי שיוצרים את הסטרימינג. כדי לעשות זאת, שולחים בקשה לכתובת ה-URL לעדכון הסשן.
גוף בקשה לדוגמה
https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session
{
key1 : "value1",
stream_parameter1 : "value2"
}
דוגמה לגוף התגובה
Successful response would be to look for - HTTP/1.1 200
מגבלות
אם משתמשים ב-API בתצוגות אינטרנט, ההגבלות הבאות חלות על טירגוט:
- סוכן משתמש: פרמטר סוכן המשתמש מועבר כערך ספציפי לדפדפן במקום כפלטפורמה הבסיסית.
-
rdid,idtype,is_lat: מזהה המכשיר לא מועבר בצורה תקינה, ולכן היכולות של התכונות הבאות מוגבלות:- מכסת תדירות
- סבב מודעות ברצף
- פילוח קהלים וטירגוט
שיטות מומלצות
חשוב לזכור שנקודת הקצה של המטא-נתונים לאינדקסים של סטרימינג בשידור חי מבוססת על הקידומת של תג ה-ID3 המתאים. ההתנהגות הזו היא מכוונת, כדי למנוע שימוש בנקודת הקצה של המטא-נתונים לשליחת פינג מיידי לכל צמתי האימות.