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

בעזרת Google DAI API אפשר להטמיע מקורות נתונים התומכים ב-Google DAI בסביבות שבהן הטמעת ה-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 תומך בשידורים לינאריים (בשידור חי) עם פרוטוקול 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 בתדירות התשאול, באמצעות כתובת ה-URL של המטא-נתונים. אם לא מציינים שום אפשרות בתגובה לזרם, מרווח הזמן המומלץ כברירת מחדל הוא 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

אתם יכולים לאמת אירועי מעקב ב-Stream Activity Monitor.

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, המגבלות הבאות חלות על הטירגוט:

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

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

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

משאבים נוספים