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

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

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

Pod Serving API תומך בשידורים של Pod Serving בפרוטוקולי סטרימינג מסוג 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 שמכיל את פרמטרי הטירגוט של המודעה. חובה

תגובת JSON

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

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

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -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 ולאחסן את הערכים הרלוונטיים.

שליחת בקשה למניפסט של הסטרימינג מהכלי לניהול המניפסטים

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

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

בקשה לדוגמה (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 המיקום שבו המודעה הזו מופיעה בתוך קבוצת המודעות בהפסקה למודעה, בשניות עם נקודה צפה.
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 בתוך הפס. לכל תג מטא-נתונים יש את המזהה TXXX, והערך מתחיל במחרוזת google_ ואחריה מופיעה סדרה של תווים. הערך הזה הוא מזהה האירוע של המודעה.

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

דוגמה לתג ID3

TXXXgoogle_1234567890123456789

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

תיבת emsg לדוגמה

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

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

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

בחלק מספריות נגני המדיה מוצגים באופן אוטומטי אירועי emsg שמחקים תגי ID3 בתור תגי ID3 מקומיים. במקרה כזה, תגי ID3 זהים מופיעים בסטרימינג של MP4 כמו ב-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

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