הכנת הלקוח להפניה אוטומטית להצגת מודעות ב-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": "8d2b2292-6356-4c0e-94be-cece01d2df2e: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 לנקודת הקצה. פרטים נוספים מופיעים במאמר בנושא שיטה: מטא-נתונים.

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

   const response = await fetch(metadata_url);
   console.log(await response.json());
   

   אם הפעולה בוצעה ללא שגיאות, תקבלו את התגובה PodMetadata לגבי הפסקות הפרסום הנוכחיות והקרובות:

   {
     "tags":{
       "google_5555555555":{
         "ad":"0000229834_ad1",
         "ad_break_id":"0000229834",
         "type":"firstquartile"
       },
       "google_1234567890123456789":{
         "ad":"0000229834_ad1",
         "ad_break_id":"0000229834",
         "type":"progress"
       },
       ...
     },
     "ads":{
       "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15,
         "clickthrough_url":"https://.../",
         ...
       },
             ...
     },
     "ad_breaks":{
       "0000229834":{
         "type":"mid",
         "duration":15,
         "ads":1
       },
       ...
     }
   }
   

3. שומרים את אובייקט tags לשלבים הבאים.

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

טוענים את השידור לנגן הווידאו

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

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

   TXXXgoogle_1234567890123456789
   

הצגת נתוני אירועים שקשורים למודעות

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

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

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

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

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_5555555555123456789`;
   
   const response = await fetch(completeUrl);
   

   אם הפעולה בוצעה ללא שגיאות, תקבלו תשובה עם קוד סטטוס 202. אחרת, תקבלו קוד שגיאה 404.

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