Google DAI Pod serving API מאפשר לכם להוסיף מודעות בצד השרת שמופעלות על ידי Google Ads, תוך שמירה על שליטה ביצירת חיבור הסרטונים.
במדריך הזה מוסבר איך להשתמש ב-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: /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 ושומרים את הערכים הרלוונטיים.
יש לבקש את המניפסט של השידור ממפעיל המניפסט
לכל מפעיל מניפסט יש פורמט שונה של בקשה ותגובה. עליכם לפנות לספק המפעיל כדי להבין את הדרישות הספציפיות שלו. אם אתם מטמיעים מניפולציית מניפסט משלכם, קראו את המדריך למניפולציית המניפסט כדי להבין את הדרישות לגבי הרכיב הזה.
באופן כללי, כדי שהמערכת תוכל ליצור מניפסטים ספציפיים לסשנים, עליכם להעביר את מזהה השידור שהוחזר על ידי נקודת הקצה של הרישום למעלה אל המניפולציה של המניפסט. התגובה לבקשת המניפסט היא וידאו בסטרימינג שמכיל תוכן וגם מודעות, אלא אם צוין אחרת במפורש על ידי ספק המניפסט.
בקשה לדוגמה (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 , המזהה המלא של אירוע המודעה.
כל ערך הוא אובייקט שמכיל את הפרמטרים הבאים:
|
||||||||||||||||||
ads |
קבוצה של צמדי מפתח/ערך שמתארים את כל המודעות שמופיעות בשידור. המפתחות הם מזהי מודעות שתואמים לערכים שנמצאים באובייקט tags שצוין למעלה. כל ערך הוא אובייקט שמכיל את הפרמטרים הבאים:
|
||||||||||||||||||
ad_breaks |
קבוצה של צמדי מפתח/ערך שמתארים את כל ההפסקות למודעות שמופיעות בשידור.
המפתחות הם מזהים של הפסקות למודעות שתואמים לערכים באובייקטים tags ו-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
.
התאמת הערכים האלה היא תהליך דו-שלבי:
צריך לחפש באובייקט
tags
מפתח שתואם למזהה המלא של אירוע המודעה. אם נמצאה התאמה, מאחזרים את סוג האירוע ואת האובייקטיםad
ו-ad_break
המשויכים אליו. האירועים האלה צריכים להיות מסוגprogress
.אם לא נמצאה התאמה למזהה המלא של אירוע המודעה, מחפשים באובייקט
tags
מפתח שתואם ל-17 התווים הראשונים של מזהה אירוע המודעה. מאחזרים את סוג האירוע ואת האובייקטיםad
ו-ad_break
המשויכים אליו. הפעולה הזו אמורה לאחזר את כל האירועים עם סוגים שאינםprogress
.אפשר להשתמש במידע המאוחזר הזה כדי לעדכן את ממשק המשתמש של הנגן. לדוגמה, כשמקבלים אירוע
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