אפליקציית נגן וידאו של לקוח לשידורי 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

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

פרמטרים של גוף ה-JSON

תגובת JSON

בקשה לדוגמה (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 שמכיל את הפרמטרים הבאים:

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

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

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

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