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

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

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

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

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

  • בודקים אם 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, מאתרים את מזהה הסשן של מקור הנתונים ושומרים נתונים אחרים לשלבים הבאים.

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

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

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

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