אפליקציית נגן וידאו של לקוח לשידורי VOD

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 תומך בשידורי pod ב-HLS או ב-MPEG-DASH ופרוטוקולים לסטרימינג. המדריך הזה מתמקד בשידורים בפרוטוקול HLS ומדגיש את המפתח הבדלים בין HLS ל-MPEG-DASH בשלבים מסוימים.

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

שליחת בקשת הרשמה לשידור אל Ad Manager

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

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

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

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

{network_code}

הקוד שלך ברשת Google Ad Manager 360

פרמטרים של גוף הקובץ JSON

targeting_parameters

אובייקט JSON שמכיל את מזהה מקור התוכן (cmsid), מזהה הווידאו (vid) ו טירגוט מודעות . חובה

תגובת 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 \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

דוגמה לתגובה

{
  "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 אורך המודעה בשניות עם נקודה צפה (floating-point). clickthrough_url כתובת ה-URL שאמורה להיפתח כשמשתמש מקיים אינטראקציה עם מודעה זו, אם נתמכת.
ad_breaks	קבוצה של צמדי מפתח/ערך שמתארים את כל ההפסקות למודעות שמופיעות בשידור. המפתחות הם מזהים של הפסקות למודעות שתואמים לערכים שנמצאו ב-tags ו-ads האובייקטים שצוינו למעלה. כל ערך הוא אובייקט שכולל את הפרמטרים הבאים: type סוג ההפסקה למודעה. סוגי ההפסקות למודעות הם pre (לפני סרטון), mid (מודעה באמצע סרטון (mid-roll)) ו-post (בסוף הסרטון). duration משך ההפסקה למודעה בשניות עם נקודה צפה (floating-point). 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, הם נשלחים כאירועי emsg 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.

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

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

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

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

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