במדריך הזה נסביר איך לפתח אפליקציית לקוח כדי לטעון שידור חי ב-HLS או ב-DASH באמצעות Pod Serving API והכלי להטמעת מודעות ותגי מעקב בקובצי פלייליסט.
דרישות מוקדמות
לפני שממשיכים, צריך:
מפתח נכס מותאם אישית לאירוע בשידור חי שהוגדר עם סוג DAI של
Pod serving redirect. כדי לקבל את המפתח הזה, צריך לפעול לפי ההוראות הבאות:משתמשים בספריית לקוח של SOAP API כדי לקרוא ל-method
LiveStreamEventService.createLiveStreamEventsעם אובייקטLiveStreamEvent, כשהמאפייןdynamicAdInsertionTypeמוגדר לערך ה-enumPOD_SERVING_REDIRECT. לכל ספריות הלקוח, ראו ספריות לקוח וקוד לדוגמה.
בודקים אם Interactive Media Ads (IMA) SDK זמין לפלטפורמה שלכם. כדי להגדיל את ההכנסות, מומלץ להשתמש ב-IMA SDK. פרטים נוספים זמינים במאמר הגדרת IMA SDK ל-DAI.
שליחת בקשה לשידור
כשהמשתמש בוחר שידור, מבצעים את הפעולות הבאות:
שולחים בקשת
POSTל-method של שירות הסטרימינג בשידור חי. לפרטים נוספים, ראו Method: stream.מעבירים פרמטרים של טירגוט מודעות בפורמטים
application/x-www-form-urlencodedאוapplication/json. הבקשה הזו רושמת סשן של שידור ב-Google DAI.בדוגמה הבאה נשלחת בקשה לסטרימינג:
קידוד הטופס
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const params = new URLSearchParams({ cust_params: 'section=sports&page=golf,tennis' }).toString(); const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: params }); console.log(await response.json());קידוד JSON
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ cust_params: { section: 'sports', page: 'golf,tennis' } }) }); console.log(await response.json());אם הפעולה בוצעה בהצלחה, הפלט אמור להיראות כך:
{ "stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS", "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/", "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata", "session_update_url": "https://dai.google.com/linear/.../session", "polling_frequency": 10 }בתגובת ה-JSON, מאתרים את מזהה הסשן של השידור ושומרים נתונים אחרים לשלבים הבאים.
מטא-נתונים של מודעות סקרים
כדי לדגום מטא-נתונים של מודעות:
קוראים את הערך
metadata_urlמהתגובה לרישום הסטרימינג.שולחים בקשת
GETראשונית לנקודת הקצה (endpoint) שלmetadata_url.- משמיטים את פרמטר השאילתה
delta_token. התהליך הזה מאפשר לשרת להחזיר את המטא-נתונים המלאים של טווח הזמן שהוגדר ל-DVR בשידור. טווח הזמן שהוגדר ל-DVR מכיל את מסגרת הזמן של השידור שזמינה לצופה כדי להריץ אחורה ולהפעיל. התשובה כוללת את השדהnext_delta_token.
- משמיטים את פרמטר השאילתה
כדי לבצע אופטימיזציה של רוחב הפס, צריך לשמור את הערך
next_delta_tokenמהתגובה האחרונה.בבקשה הבאה, שולחים את הערך הזה בתור פרמטר השאילתה
delta_token. השרת מחזיר רק את המטא-נתונים שהשתנו מאז שהאסימון נוצר. תמיד צריך לשלוח את הטוקן האחרון שקיבלתם. אל תנסו לנתח, לשנות או ליצור את האסימון. למידע נוסף, קראו את המאמר Method: metadata.בדוגמה הבאה מתבצעת אחזור של מטא-נתונים של מודעות:
// Initial request (returns full metadata and next_delta_token) let response = await fetch(metadata_url); let metadata = await response.json(); let deltaToken = metadata.next_delta_token; // Subsequent request (returns only changes since deltaToken) if (deltaToken) { const url = new URL(metadata_url); url.searchParams.append('delta_token', deltaToken); response = await fetch(url.toString()); const deltaMetadata = await response.json(); // Merge deltaMetadata into your local cache mergeMetadata(metadata, deltaMetadata); deltaToken = deltaMetadata.next_delta_token; }אם הפעולה בוצעה ללא שגיאות, תתקבל התשובה PodMetadata. אם תספקו את הפרמטר
delta_token, התשובה תכיל רק את המודעות, ההפסקות למודעות והתגים שהשרת הוסיף או עדכן מאז שהשרת יצר את האסימון. התגובה מכילה גם ערךnext_delta_tokenחדש. אם יש הפסקות למודעות שהן לא עדכניות, התגובה כוללת גם רשימתobsolete_ad_break_idsשל ההפסקות למודעות שצריך להסיר מהמטמון.{ "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", "clickthrough_url":"https://.../", ... }, ... }, "ad_breaks":{ "0003069408":{ "type":"mid", "duration":30, "ads":3 }, ... } }שומרים את האובייקט
tagsוממזגים את העדכונים במטמון המקומי. אם הפרמטרobsolete_ad_break_idsקיים, צריך להסיר מהמטמון את ההפסקות למודעות ואת המודעות והתגים שמשויכים אליהן.מגדירים טיימר באמצעות הערך
polling_frequencyכדי לבקש מטא-נתונים באופן קבוע. בכל סקר, שולחים את הערךnext_delta_tokenשהוחזר בתגובה האחרונה של המטא-נתונים כפרמטר השאילתהdelta_token.
טוענים את השידור בנגן הווידאו
אחרי שמקבלים את מזהה הסשן מהתגובה לרישום, מעבירים את המזהה לכלי להטמעת מודעות ותגי מעקב בקובצי פלייליסט, או יוצרים כתובת URL של קובץ פלייליסט כדי לטעון את השידור לנגן וידאו.
כדי להעביר את מזהה הסשן, עיינו במסמכי התיעוד של הכלי להטמעת מודעות ותגי מעקב בקובצי פלייליסט. אם אתם מפתחים כלי להטמעת מודעות ותגי מעקב בקובצי פלייליסט, עיינו במאמר כלי להטמעת מודעות ותגי מעקב בקובצי פלייליסט לשידור חי.
בדוגמה הבאה מוצג איך להרכיב כתובת URL של מניפסט:
https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"
כשהנגן מוכן, מתחילים את ההפעלה.
האזנה לאירועים של מודעות
בודקים את פורמט המאגר של השידור כדי למצוא את המטא-נתונים המתוזמנים:
בשידורי HLS עם מאגרי Transport Stream (TS) נעשה שימוש בתגי ID3 מתוזמנים כדי להעביר מטא-נתונים מתוזמנים. לפרטים נוספים, קראו את המאמר מידע על Common Media Application Format עם HTTP Live Streaming (HLS).
בסטרימינג ב-DASH, רכיבי
EventStreamמשמשים לציון אירועים במניפסט.שידורי DASH משתמשים ברכיבי
InbandEventStreamכשהקטעים מכילים תיבות של הודעות אירוע (emsg) לנתוני מטען ייעודי (payload), כולל תגי ID3. לפרטים, ראו InbandEventStream.בשידורי CMAF, כולל DASH ו-HLS, נעשה שימוש בתיבות
emsgשמכילות תגי ID3.
כדי לאחזר תגי ID3 מהשידור, עיינו במדריך של נגן הווידאו. למידע נוסף, קראו את המדריך לטיפול במטא-נתונים מתוזמנים.
כדי לאחזר את מזהה אירוע המודעה מתגי ID3, מבצעים את הפעולות הבאות:
- מסננים את האירועים לפי
scheme_id_uriעםurn:google:dai:2018אוhttps://aomedia.org/emsg/ID3. מחלצים את מערך הבייטים מהשדה
message_data.בדוגמה הבאה, הנתונים של
emsgמפוענחים ל-JSON:{ "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3", "presentation_time": 27554, "timescale": 1000, "message_data": "ID3TXXXgoogle_1022389921", ... }מסננים את תגי ה-ID3 בפורמט
TXXXgoogle_{ad_event_ID}:TXXXgoogle_1022389921
הצגת נתונים של אירועי מודעות
כדי למצוא את האובייקט TagSegment:
מאחזרים את האובייקט
tagsשל המטא-נתונים של המודעה מתוך Poll ad metadata. האובייקטtagsהוא מערך של אובייקטים מסוגTagSegment.משתמשים במזהה המלא של אירוע המודעה כדי למצוא אובייקט
TagSegmentמסוגprogress.משתמשים ב-17 התווים הראשונים של מזהה האירוע של המודעה כדי למצוא אובייקט
TagSegmentמסוגים אחרים.מכיוון שאפליקציית הלקוח דוגמת את המטא-נתונים של המודעות מדי פעם, יכול להיות שיהיה עיכוב בין המועד שבו נגן הווידאו נתקל בתג ID3 בסטרימינג לבין המועד שבו המטא-נתונים המשויכים זמינים. אם אפליקציית הלקוח לא מוצאת תג ID3 בתגים השמורים, צריך לשמור את התג בתור ולעבד אותו מחדש אחרי הסקר הבא של המטא-נתונים. השאירו את התג בתור עד לסיום העיבוד.
אחרי שמקבלים את
TagSegment, משתמשים במאפייןad_break_idכמפתח כדי למצוא את האובייקטAdBreakבאובייקט המטא-נתונים של המודעהad_breaks.בדוגמה הבאה מוצאים אובייקט
AdBreak:{ "type":"mid", "duration":15, "ads":1 }משתמשים בנתונים של
TagSegmentו-AdBreakכדי להציג מידע על מיקום המודעה בהפסקה למודעה. לדוגמה,Ad 1 of 3.
שליחת פינגים לאימות מדיה
לכל אירוע מודעה, חוץ מהסוג progress, צריך לשלוח פינג לאימות מדיה.
מערכת Google DAI מתעלמת מאירועי progress, ושליחה תכופה של האירועים האלה עלולה לפגוע בביצועי האפליקציה.
כדי ליצור את כתובת ה-URL המלאה לאימות המדיה של אירוע מודעה:
מהתגובה של השידור, מוסיפים את המזהה המלא של אירוע המודעה לערך של
media_verification_url.שולחים בקשת
GETעם כתובת ה-URL המלאה:// media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/" const completeUrl = `${media_verification_url}google_1022389921`; const response = await fetch(completeUrl);אם הפעולה מצליחה, תתקבל תשובה עם קוד סטטוס
202. אחרת, תתקבל הודעת השגיאה404.
אתם יכולים להשתמש בכלי לניהול שידור (SAM) כדי לבדוק את היומן ההיסטורי של כל אירועי המודעות. פרטים נוספים זמינים במאמר מעקב ופתרון בעיות בשידור חי.