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

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

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

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

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

שליחת בקשת רישום של מקור נתונים ל-DAI Pod serving API

שולחים בקשת 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/x-www-form-urlencoded

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

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

פרמטרים גופניים מקודדים בפורמט

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

תגובת 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/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

דוגמה לתגובה

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

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

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

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

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

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

בקשה לדוגמה (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

הפעלת השידור

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

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

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

בתמורה לכך, אתם מקבלים אובייקט 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.

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

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

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

HTTP/1.1 202 Accepted

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