אפליקציית נגן הווידאו של הלקוח לסטרימינג בשידור חי

Google DAI Pod serving API מאפשר לכם להוסיף מודעות בצד השרת שמופעלות על ידי Google Ads, תוך שמירה על שליטה ביצירת חיבור הסרטונים.

נקודה חשובה: לפני שתשקלו להשתמש ב-API הזה, בדקו אם כבר יש IMA DAI SDK לפלטפורמה שבחרתם. מומלץ להשתמש ב-IMA DAI SDK בפלטפורמות שבהן הוא זמין. Pod serving API מיועד לשימוש רק בפלטפורמות שאין להן IMA DAI SDK.

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

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

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

שליחת בקשה לרישום מקור נתונים ב-Ad Manager

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

נקודת הקצה ל-API

POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/json

פרמטרים של נתיב

{network_code}	הקוד שלך ברשת Google Ad Manager 360
{custom_asset}	המזהה המותאם אישית שמשויך לאירוע הזה ב-Google AdManager.

פרמטרים של גוף שמקודדים בטופס

קבוצה אופציונלית של פרמטרים של מיקוד בקידוד טופס.

קובץ JSON של התשובה

media_verification_url	כתובת ה-URL הבסיסית לאירועי מעקב אחר הפעלה. כדי ליצור כתובת URL מלאה לאימות מדיה, צריך לצרף מזהה אירוע מודעה לכתובת ה-URL הבסיסית הזו.
metadata_url	כתובת ה-URL שעבורה יש לבקש מטא-נתונים של רצף מודעות.
stream_id	המחרוזת שמשמשת לזיהוי סשן השידור הנוכחי.
valid_for	משך הזמן שנותר עד לסיום הסשן הנוכחי, בפורמט dhms (ימים, שעות, דקות, שניות). לדוגמה, 2h0m0.000s מייצג משך זמן של שעתיים.
valid_until	המועד שבו יפוג תוקף הסשן הנוכחי של השידור, כמחרוזת תאריך ושעה לפי ISO 8601 בפורמט yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.

בקשה לדוגמה (cURL)

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded"
     -d "cust_params="section%3Dsports%26page%3Dgolf%2Ctennis"
  https://dai.google.com/linear/pods/api/v1/network/21775744923/custom_asset/an-public-test-asset/stream

דוגמה לתגובה

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

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

מנתחים את תגובת ה-JSON ושומרים את הערכים הרלוונטיים.

טיפ: כתובות ה-URL שצוינו בתגובת ה-API עשויות להשתנות ללא הודעה. לכן, כדאי להשתמש בכתובות ה-URL שצוינו בתגובת ה-API במקום ליצור אותן בעצמכם. כך הקוד שלכם ימשיך לפעול בצורה תקינה כשכתובות ה-URL משתנות.

יש לבקש את המניפסט של השידור ממפעיל המניפסט

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

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

בקשה לדוגמה (cURL)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

דוגמה לתגובה (HLS)

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

הפעלת השידור

טוענים את המניפסט שקיבלתם משרת שינוי המניפסט לנגן וידאו ומתחילים את ההפעלה.

בקשת מטא-נתונים של רצף מודעות מ-Ad Manager

צריך לשלוח בקשת GET אל metadata_url שקיבלת בשלב הראשון. השלב הזה חייב להתבצע אחרי שמקבלים את המניפסט שהותאם ממניפול המניפסט. כשתקבלו אובייקט JSON שמכיל את הפרמטרים הבאים:

tags	קבוצה של צמדי מפתח/ערך שמכילים את כל אירועי המודעות שמופיעים בזרם. המפתחות הם 17 התווים הראשונים של מזהה אירוע מודעה שמופיעים במטא-נתונים המתוזמן של מקור נתונים. לחלופין, במקרה של אירועים מסוג progress, המזהה המלא של אירוע המודעה. כל ערך הוא אובייקט שמכיל את הפרמטרים הבאים: ad המזהה של מודעה שתואמת למפתח באובייקט ads. ad_break_id המזהה של ההפסקה למודעה שתואם למפתח באובייקט ad_breaks. type הסוג של אירוע המודעה. סוגי האירועים של המודעות: start מופעל בתחילת המודעה. firstquartile מופעל בסוף הרבעון הראשון. midpoint מופעלת בנקודת האמצע של המודעה. thirdquartile מופעל בסוף הרבעון השלישי. complete מופעל בסוף המודעה. progress מופעלת מדי פעם במהלך המודעה, כדי להודיע לאפליקציה שמופעלת הפסקה למודעה.
ads	קבוצה של צמדי מפתח/ערך שמתארים את כל המודעות שמופיעות בשידור. המפתחות הם מזהי מודעות שתואמים לערכים שנמצאים באובייקט tags שצוין למעלה. כל ערך הוא אובייקט שמכיל את הפרמטרים הבאים: ad_break_id המזהה של ההפסקה למודעה שתואם למפתח באובייקט ad_breaks. position המיקום שבו המודעה הזו מופיעה בתוך קבוצת המודעות בהפסקת המודעות, בשניות של נקודה צפה (floating-point). duration משך המודעה בנקודה צפה (בשניות). clickthrough_url כתובת ה-URL שאמורה להיפתח כשמשתמש מקיים אינטראקציה עם המודעה הזו, אם היא נתמכת.
ad_breaks	קבוצה של צמדי מפתח/ערך שמתארים את כל ההפסקות למודעות שמופיעות בשידור. המפתחות הם מזהים של הפסקות למודעות שתואמים לערכים באובייקטים tags ו-ads שמפורטים למעלה. כל ערך הוא אובייקט שמכיל את הפרמטרים הבאים: type סוג ההפסקה למודעה. סוגי ההפסקות למודעות הם pre (מודעה לפני סרטון), mid (מודעה באמצע סרטון) ו-post (מודעה בסוף סרטון). duration משך ההפסקה למודעה בנקודה צפה (בשניות). ads מספר המודעות בהפסקה הזו למודעות.

כדאי לאחסן את הערכים האלה כדי לשייך אותם לאירועי מטא-נתונים מתוזמנים בתוך שידור הווידאו.

בקשה לדוגמה (cURL)

curl https://dai.google.com/.../metadata

דוגמה לתגובה

{
  "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
    },
    ...
  }
}

האזנה לאירועי מודעות

האזנה למטא-נתונים מתוזמנים דרך אירועי מודעות שהופעלו בזרם האודיו/וידאו של נגן הווידאו.

עבור שידורי MPEG-TS, המטא-נתונים מופיעים כתגי ID3 v2.3 in-band. לכל תג מטא-נתונים יש את המזהה TXXX, והערך מתחיל במחרוזת google_ ואחריה סדרת תווים. הערך הזה הוא מזהה האירוע של המודעה.

הערך XXX ב-TXXX אינו placeholder. המחרוזת TXXX היא המזהה של תג ה-ID3 השמור עבור 'טקסט בהגדרת משתמש'.

דוגמה לתג ID3

TXXXgoogle_1234567890123456789

בשידורי MP4, האירועים האלה נשלחים כאירועי הודעות in-band שמדמים תגי ID3 v2.3. לכל תיבת הודעות רלוונטית יש את הערך scheme_id_uri https://aomedia.org/emsg/ID3 או https://developer.apple.com/streaming/emsg-id3 וערך message_data שמתחיל ב-ID3TXXXgoogle_. הערך message_data, בלי הקידומת ID3TXXX, הוא מזהה האירוע של המודעה.

דוגמה לתיבת הודעות

מבנה הנתונים עשוי להשתנות בהתאם לספריית נגן המדיה.

אם המזהה של אירוע המודעה הוא google_1234567890123456789, התשובה תיראה כך:

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

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

עדכון ממשק המשתמש של אפליקציית נגן הווידאו של הלקוח

החל משלב 4, ניתן להתאים כל מזהה של אירוע מודעה למפתח באובייקט tags. התאמת הערכים האלה היא תהליך דו-שלבי:

1. צריך לחפש באובייקט tags מפתח שתואם למזהה המלא של אירוע המודעה. אם נמצאה התאמה, מאחזרים את סוג האירוע ואת האובייקטים ad ו-ad_break המשויכים אליו. האירועים האלה צריכים להיות מסוג progress.

   אם לא נמצאה התאמה למזהה המלא של אירוע המודעה, מחפשים באובייקט tags מפתח שתואם ל-17 התווים הראשונים של מזהה אירוע המודעה. מאחזרים את סוג האירוע ואת האובייקטים ad ו-ad_break המשויכים אליו. הפעולה הזו אמורה לאחזר את כל האירועים עם סוגים שאינם progress.

2. אפשר להשתמש במידע המאוחזר הזה כדי לעדכן את ממשק המשתמש של הנגן. לדוגמה, כשאתה מקבל start או את האירוע הראשון של progress, עליך להסתיר את פקדי ההרצה של הנגן ולהציג שכבת-על שמתארת את המיקום הנוכחי של המודעה בהפסקה למודעה. לדוגמה: "מודעה 1 מתוך 3".

מזהים של אירועי מודעות לדוגמה

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

אובייקט של תגים לדוגמה

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

שליחת פינגים לאימות מדיה

פינג לאימות מדיה צריך להישלח ל-Ad Manager בכל פעם שמתקבל אירוע מודעה מסוג שאינו progress.

כדי ליצור את כתובת ה-URL המלאה לאימות מדיה עבור אירוע מודעה, צריך לצרף את המזהה המלא של האירוע במודעה לערך media_verification_url מתגובת ההרשמה לשידור.

צריך להגיש בקשת GET עם כתובת ה-URL המלאה. אם בקשת האימות תאושר, תקבלו תגובת HTTP עם קוד הסטטוס 202. אחרת, תקבלו את קוד שגיאת ה-HTTP 404.

טיפ: אין לשלוח אל Ad Manager אירועי מודעות מסוג progress. המטרה של האירועים האלה היא ליידע את אפליקציית נגן הווידאו של הלקוח על כך שיש הפסקה למודעה במצבים שבהם יכול להיות שאירוע ההתחלה לא התקבל. לדוגמה, אם המשתמש מבקש להגיע למיקום מסוים או מתחיל את ההפעלה בחותמת זמן ספציפית שמופיעה באמצע המודעה, הוא לא יקבל אירוע התחלה. אירועי התקדמות שנשלחים ל-Ad Manager נמחקים, מה שעלול להשפיע לרעה על הביצועים של האפליקציה.

בקשה לדוגמה (cURL)

curl https://{...}/media/google_5555555555123456789

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

HTTP/1.1 202 Accepted

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

• מסמכי הפניית API
• מסמכי תיעוד של IMA SDK
• השוואה בין סוגי הטמעה של שכבות DAI