הכנת הלקוח להפניה אוטומטית להצגת מודעות ב-pod

במדריך הזה מוסבר איך לפתח אפליקציית לקוח לטעינת שידור חי בפורמט HLS או DASH באמצעות Pod Serving API וכלי לשינוי מניפסט.

דרישות מוקדמות

לפני שממשיכים, צריך לוודא שיש לכם את הדברים הבאים:

• מפתח נכס בהתאמה אישית לאירוע בשידור חי שהוגדר עם סוג ה-DAI‏ Pod serving redirect. כדי לקבל את המפתח הזה, צריך לפעול לפי השלבים הבאים:

  • הגדרת שידור חי ל-DAI

  • משתמשים בספריית לקוח של SOAP API כדי להפעיל את השיטה LiveStreamEventService.createLiveStreamEvents עם אובייקט LiveStreamEvent והמאפיין dynamicAdInsertionType שמוגדר לערך POD_SERVING_REDIRECT של enum. במאמר ספריות לקוח וקוד לדוגמה מפורטות כל ספריות הלקוח.

• בודקים אם Interactive Media Ads (IMA) SDK זמין לפלטפורמה שלכם. מומלץ להשתמש ב-IMA SDK כדי להגדיל את ההכנסות. פרטים נוספים זמינים במאמר בנושא הגדרה של IMA SDK ל-DAI.

שליחת בקשה לשידור

כשהמשתמש בוחר בסטרימינג, צריך לבצע את הפעולות הבאות:

1. שולחים בקשת POST לשיטת שירות השידור החי. לפרטים נוספים, ראו השיטה: stream.

2. העברת פרמטרים של טירגוט מודעות בפורמט 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
   }
   

3. בתגובת ה-JSON, מאתרים את מזהה הסשן של מקור הנתונים ושומרים נתונים אחרים לשלבים הבאים.

   חשוב: כדי שהאפליקציה תפעל, צריך להשתמש ישירות בכתובות ה-URL שמופיעות בתשובה. אל תיצרו את כתובות ה-URL, כי יכול להיות שהנתיבים ישתנו.

מטא-נתונים של מודעות בסקרים

כדי לבצע סקר לגבי מטא-נתונים של מודעות:

1. קוראים את הערך metadata_url מהתגובה של רישום הזרם.

2. שליחת בקשת GET ראשונית לנקודת הקצה metadata_url.

   • משמיטים את פרמטר השאילתה delta_token. התהליך הזה מאפשר לשרת להחזיר את המטא-נתונים המלאים של חלון ה-DVR של הסטרימינג. חלון ה-DVR מכיל את מסגרת הזמן של השידור שזמינה לצופים להרצה לאחור ולהפעלה. התשובה כוללת את השדה next_delta_token.

3. כדי לבצע אופטימיזציה של רוחב הפס, מאחסנים את הערך next_delta_token מהתגובה האחרונה.

4. בבקשה הבאה, שולחים את הערך הזה כפרמטר השאילתה delta_token. השרת מחזיר רק את המטא-נתונים שהשתנו מאז יצירת הטוקן. תמיד שולחים את האסימון האחרון שקיבלתם. אל תנסו לנתח, לשנות או ליצור את הטוקן. לפרטים נוספים, אפשר לעיין במאמר בנושא שיטה: מטא-נתונים.

   בדוגמה הבאה מתבצעת אחזור של מטא-נתונים של מודעות:

   // 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
       },
       ...
     }
   }
   

5. שומרים את אובייקט tags וממזגים את העדכונים במטמון המקומי. אם הפרמטר obsolete_ad_break_ids מופיע, מסירים מהמטמון את ההפסקות האלה למודעות ואת המודעות והתגים שמשויכים אליהן.

6. מגדירים טיימר באמצעות הערך 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 מתוזמנים כדי להעביר מטא-נתונים מתוזמנים. לפרטים נוספים, אפשר לעיין במאמר בנושא פורמט נפוץ של אפליקציות מדיה עם HTTP Live Streaming ‏(HLS).

• בסטרימינג ב-DASH נעשה שימוש ברכיבי EventStream כדי לציין אירועים במניפסט.

• בסטרימינג של DASH נעשה שימוש ברכיבי InbandEventStream כשהקטעים מכילים תיבות של הודעות אירוע (emsg) לנתוני מטען ייעודי, כולל תגי ID3. פרטים נוספים זמינים במאמר בנושא InbandEventStream.

• בסטרימינג בפורמט CMAF, כולל DASH ו-HLS, נעשה שימוש בemsgתיבות שמכילות תגי ID3.

כדי לאחזר תגי ID3 מהסטרימינג, אפשר לעיין במדריך של נגן הווידאו. פרטים נוספים זמינים במאמר הוספת מטא-נתונים עם חותמות זמן.

כדי לאחזר את מזהה אירוע המודעה מתגי ID3, מבצעים את הפעולות הבאות:

1. מסננים את האירועים לפי scheme_id_uri עם urn:google:dai:2018 או https://aomedia.org/emsg/ID3.

2. מחפשים את השדה message_data ומחלצים ממנו את מערך הבייטים.

   בדוגמה הבאה, הנתונים emsg מפוענחים ל-JSON:

   {
     "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
     "presentation_time": 27554,
     "timescale": 1000,
     "message_data": "ID3TXXXgoogle_1022389921",
     ...
   }
   

3. מסננים את תגי ID3 בפורמט TXXXgoogle_{ad_event_ID}:

   TXXXgoogle_1022389921
   

הצגת נתוני אירועי מודעות

כדי למצוא את האובייקט TagSegment:

1. אחזור האובייקט tags של מטא-נתוני המודעה מ-Poll ad metadata. אובייקט tags הוא מערך של אובייקטים TagSegment.

2. משתמשים במזהה המלא של אירוע המודעה כדי למצוא אובייקט TagSegment עם הסוג progress.

3. כדי למצוא אובייקט TagSegment מסוגים אחרים, משתמשים ב-17 התווים הראשונים של מזהה האירוע שהמודעה הובילה אליו.

   אפליקציית הלקוח מבצעת שאילתות לגבי מטא-נתונים של מודעות באופן תקופתי, ולכן יכול להיות עיכוב בין הרגע שבו נגן הווידאו נתקל בתג ID3 בסטרימינג לבין הרגע שבו המטא-נתונים המשויכים זמינים. אם אפליקציית הלקוח לא מוצאת תג ID3 בתגים המאוחסנים, התג נשאר בתור והמערכת מעבדת אותו מחדש אחרי הסקר הבא של המטא-נתונים. משאירים את התג בתור עד שהעיבוד מסתיים.

4. אחרי שמקבלים את TagSegment, משתמשים במאפיין ad_break_id כמפתח כדי למצוא את האובייקט AdBreak באובייקט המטא-נתונים של המודעה ad_breaks.

   בדוגמה הבאה מוצאים אובייקט AdBreak:

   {
     "type":"mid",
     "duration":15,
     "ads":1
   }
   

5. משתמשים בנתונים TagSegment ו-AdBreak כדי להציג מידע על מיקום המודעה בהפסקה למודעה. לדוגמה, Ad 1 of 3.

שליחת פינגים לאימות מדיה

לכל אירוע שקשור למודעה, חוץ מהסוג progress, שולחים פינג לאימות מדיה. מערכת Google DAI מבטלת אירועים מסוג progress, ושליחה תכופה של האירועים האלה עלולה להשפיע על ביצועי האפליקציה.

כדי ליצור את כתובת ה-URL לאימות מדיה של אירוע מודעה, צריך:

1. מהתגובה של הסטרימינג, מוסיפים את המזהה המלא של אירוע המודעה לערך media_verification_url.

2. שולחים בקשת 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.

אתם יכולים להשתמש בכלי Stream Activity Monitor (SAM) כדי לבדוק יומן היסטורי של כל אירועי המודעות. פרטים נוספים מופיעים במאמר בנושא מעקב אחרי שידור חי ופתרון בעיות בו.