API של הטמעת מודעות דינמיות (DAI) לשידורים חיים

Google DAI API מאפשר להטמיע שידורים שכוללים DAI מבית Google בסביבות שבהן אין תמיכה בהטמעה של IMA SDK. אנחנו ממליצים להמשיך להשתמש IMA בפלטפורמות שבהן יש תמיכה ב-IMA SDK.

אנחנו ממליצים להשתמש ב-DAI API בפלטפורמות הבאות:

  • Samsung Smart TV (Tizen)
  • טלוויזיה של LG
  • HbbTV
  • Xbox (אפליקציות JavaScript)
  • KaiOS

ה-API תומך ביכולות הבסיסיות שמסופקות על ידי IMA DAI SDK. עבור לשאלות ספציפיות על תאימות או תכונות נתמכות, אפשר לפנות אל הנציג של חשבון Google.

הטמעת DAI API לסטרימינג בשידור חי

DAI API תומך בשידורים לינאריים (LIVE) באמצעות פרוטוקולים HLS ו-DASH. השלבים המתוארים במדריך הזה חלים על שני הפרוטוקולים.

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

1. איך מבקשים שידור חי

כדי לבקש שידור חי מ-DAI API, צריך לבצע קריאת POST אל השידור נקודת הקצה. תגובת ה-JSON מכילה את המניפסט של השידור וגם את השיוך שלו נקודות קצה וערכים של DAI API.

דוגמה לגוף הבקשה

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

דוגמה לגוף התשובה

{
"stream_id":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

תגובה עם שגיאה

אם יש שגיאות, מוחזרים קודי שגיאות HTTP רגילים ללא תגובת JSON גוף ההודעה.

נתח את תגובת ה-JSON ואחסן את הערכים הבאים:

stream_id
אפשר להשתמש בערך הזה כדי לזהות את השידור שהוחזר.
stream_manifest
כתובת ה-URL הזו מועברת לנגן המדיה לצורך הפעלת השידור.
media_verification_url
כתובת ה-URL הזו היא נקודת הקצה הבסיסית למעקב אחר אירועי הפעלה.
metadata_url
כתובת ה-URL הזו משמשת לבדיקת מידע תקופתי לגבי שידורים קרובים אירועים.
session_update_url
כתובת ה-URL הזו משמשת לעדכון הפרמטרים של הבקשה לשידור חי שנשלחו במהלך בקשה לשידור בסטרימינג. לתשומת ליבך, הפרמטרים של הבקשה הזו מחליפים את כל הפרמטרים מוגדר לשידור המוקדם יותר.
polling_frequency
התדירות, בשניות, כשמבקשים מטא-נתונים מעודכנים של AdBreak DAI API.

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

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

דוגמה לגוף הבקשה

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

דוגמה לגוף התשובה

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },......
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },....
   }
}

3. האזנה לאירועי ID3 ומעקב אחר אירועי הפעלה

כדי לוודא שאירועים ספציפיים קרו בווידאו בסטרימינג, צריך לפעול לפי השלבים הבאים שלבים לטיפול באירועי ID3:

  1. אחסון אירועי המדיה בתור, ושמירה של כל מזהה מדיה יחד עם חותמת זמן (אם הנגן מציג זאת).
  2. בכל פעם עדכון מהנגן, או בתדירות מוגדרת (מומלץ 500 אלפיות השנייה), אפשר לבדוק את התור לאירועי המדיה של אירועים שהופעלו לאחרונה על ידי השוואה בין חותמות הזמן של האירוע לבין המיקום הנוכחי.
  3. כדי לבדוק אירועי מדיה שהושמעו, אפשר לבדוק את הסוג שלהם מזהה המדיה בתגי ההפסקות למודעות שנשמרו. חשוב לזכור שהתגים השמורים מכילים רק קידומת של מזהה המדיה, כך שלא ניתן להשתמש בהתאמה מדויקת.
  4. איך משתמשים ב'התקדמות' אירועים כדי לעקוב אחרי מקרים שבהם משתמש נמצא בהפסקה למודעה. אל תשלחו את האירועים האלה לנקודת הקצה של אימות המדיה. לאירוע אחר שונים, מוסיפים את מזהה המדיה לנקודת הקצה של אימות המדיה ומבצעים GET בקשה למעקב אחר ההפעלה.
  5. הסרת אירוע המדיה מהתור.

דוגמה לגוף הבקשה

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

תשובות לדוגמה

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

אפשר לאמת אירועי מעקב בקטע פעילות בסטרימינג מעקב.

4. עדכון הפרמטרים של השידור החי

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

דוגמה לגוף הבקשה

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

דוגמה לגוף התשובה

Successful response would be to look for - HTTP/1.1 200

מגבלות

אם אתם משתמשים ב-API בתוך רכיבי WebView, ההגבלות הבאות חלות בהתאם לטירגוט:

  • סוכן משתמש: הפרמטר של סוכן המשתמש מועבר כערך ספציפי לדפדפן במקום בפלטפורמה הבסיסית.
  • rdid idtype, is_lat: מזהה המכשיר לא מועבר כראוי, ולכן מגבילות את היכולות של בתכונות הבאות:
    • מכסת תדירות
    • סבב מודעות ברצף
    • פילוח וטירגוט של קהל היעד

שיטות מומלצות

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

מקורות מידע נוספים