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

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

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

לפני שממשיכים, צריך:

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

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

  1. שולחים בקשת POST ל-method של שירות הסטרימינג בשידור חי. לפרטים נוספים, ראו Method: 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, מאתרים את מזהה הסשן של השידור ושומרים נתונים אחרים לשלבים הבאים.

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

כדי לדגום מטא-נתונים של מודעות:

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

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

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

  4. בבקשה הבאה, שולחים את הערך הזה בתור פרמטר השאילתה 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
        },
        ...
      }
    }
    
  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 מתוזמנים כדי להעביר מטא-נתונים מתוזמנים. לפרטים נוספים, קראו את המאמר מידע על Common Media Application Format עם HTTP Live Streaming ‏(HLS).

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

  • שידורי DASH משתמשים ברכיבי InbandEventStream כשהקטעים מכילים תיבות של הודעות אירוע (emsg) לנתוני מטען ייעודי (payload), כולל תגי 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. משתמשים ב-17 התווים הראשונים של מזהה האירוע של המודעה כדי למצוא אובייקט TagSegment מסוגים אחרים.

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

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