תחילת העבודה עם SGAI

הטמעת מודעות מונחתת על ידי שרת (SGAI) מספקת מניפסט של רצף מודעות שמוכנה לחיבור במכשירי לקוח. אם הפעלתם את האפשרות 'הצגת מודעות דינמיות במודעות רצף' ברשת שלכם ב-Google Ad Manager, יש לכם גישה לשימוש ב-SGAI. אם לא הפעלתם את האפשרות 'הצגת מודעות דינמיות במודעות Pod', עליכם לפנות למנהל החשבון שלכם.

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

אם יש לכם שרת לטיפול במניפסטים, תוכלו ליצור את כתובות ה-URL של המניפסט של רצף המודעות ולהוסיף לסטרימינג של התוכן סמנים של מודעות שנושאים את המידע מהמניפסט של רצף המודעות, בהתאם למפרט המועדף עליכם.

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

דרישות מוקדמות

לפני שממשיכים, חשוב לוודא שיש לכם את הפריטים הבאים:

  • הצגת מודעות DAI Pod מופעלת ברשת שלכם ב-Google Ad Manager.
  • אירוע בשידור חי מסוג מניפסט להצגת מודעות ב-Pod. במאמר הגדרת שידור חי ל-DAI מוסבר איך יוצרים את האירוע.

ביצוע ההמלצות

לפני שיוצרים את כתובת ה-URL של המניפסט של רצף המודעות, מומלץ לבצע קריאה ל-Early Ad Break Notification (EABN) API כדי לציין את משך הזמן הצפוי, פרטי הטירגוט ופרמטרים אחרים של כל הפסקה למודעה.

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

שליחת בקשה לרישום של שידור

כשמשתמש מתחיל סטרימינג של תוכן באפליקציית הנגן שלכם, אתם שולחים בקשה לרישום של סטרימינג עם פרמטרים של טירגוט כדי ליצור סשן סטרימינג ב-Ad Manager. פרטים על שליחת בקשה לרישום של מקור נתונים מופיעים במאמר Method:stream. לאחר מכן, תקבלו נתוני תגובה מהבקשה.

הדוגמאות הבאות ממחישות שליחת בקשה לרישום של שידור:

HTTP בטקסט פשוט קונכייה JavaScript
  • בקשה:
authority: dai.google.com
method: POST
path: /ssai/pods/api/v1/network/51636543/custom_asset/hls-podserving-manifest/stream
scheme: https
content-type: application/x-www-form-urlencoded

cust_params=customID%253D1543216789%2526anotherKey%253Dvalue1%252Cvalue2
  • תשובה:
{
    "manifest_format": "hls",
    "media_verification_url": "https://dai.google.com/view/p/service/linear/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/loc/TUL/network/51636543/event/TFyZF0IoSpqvCLtLv8JdCw/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/metadata",
    "polling_frequency": 10,
    "session_update_url": "https://dai.google.com/linear/v1/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/session",
    "stream_id": "24fd4e7c-95a0-42be-8874-00625139b9db:TUL"
}
  • שורת הפקודה:
curl \
-H "Host: dai.google.com" \
-H "content-type: application/x-www-form-urlencoded" \
  --data-binary "cust_params=channelID%253D1543216789%2526anotherKey%253Dvalue1%252Cvalue2" \
  --compressed "https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/hls-podserving-manifest/stream"
  • פלט:
{
    "manifest_format": "hls",
    "media_verification_url": "https://dai.google.com/view/p/service/linear/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/loc/TUL/network/51636543/event/TFyZF0IoSpqvCLtLv8JdCw/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/metadata",
    "pod_manifest_url": "https://dai.google.com/linear/pods/v1/hls/event/TFyZF0IoSpqvCLtLv8JdCw/pod/$pod-id$.m3u8?stream_id=24fd4e7c-95a0-42be-8874-00625139b9db%3ATUL",
    "polling_frequency": 10,
    "session_update_url": "https://dai.google.com/linear/v1/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/session",
    "stream_id": "24fd4e7c-95a0-42be-8874-00625139b9db:TUL"
}
  • באמצעות Fetch API:
const response = await fetch("https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/hls-podserving-manifest/stream", {
  "headers": {
    "content-type": "application/x-www-form-urlencoded",
  },
  "body": "cust_params=channelID%3D1543216789%26anotherKey%3Dvalue1%2Cvalue2",
  "method": "POST",
});

  const stream = await response.json();
  console.log(stream);
  • יומן מסוף:
{
    "stream_id": "24fd4e7c-95a0-42be-8874-00625139b9db:TUL",
    "media_verification_url": "https://dai.google.com/view/p/service/linear/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/loc/TUL/network/51636543/event/TFyZF0IoSpqvCLtLv8JdCw/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/metadata",
    "session_update_url": "https://dai.google.com/linear/v1/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/session",
    "polling_frequency": 10,
    "pod_manifest_url": "https://dai.google.com/linear/pods/v1/hls/event/TFyZF0IoSpqvCLtLv8JdCw/pod/$pod-id$.m3u8?stream_id=24fd4e7c-95a0-42be-8874-00625139b9db%3ATUL",
    "manifest_format": "hls"
}

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

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

יצירת כתובת ה-URL של המניפסט של רצף המודעות

יוצרים כתובת URL למשאב pod של Pod Serving API. לאחר מכן, מעבירים את כתובת ה-URL לנגן וידאו כדי להתחיל לטעינת רצף המודעות.

הדוגמה הבאה ממחישה את המבנה של כתובת ה-URL של המניפסט של רצף המודעות:

https://dai.google.com/linear/pods/v1/hls/network/51636543/custom_asset/pod_serving_hls_manifest_mp4/ad_break_id/ab101.m3u8?stream_id=24fd4e7c-95a0-42be-8874-00625139b9db:TUL&pd=120000

אפשר לחשב את הפרמטרים של כתובת ה-URL של מניפסט רצף המודעות על סמך המידע על ההפסקות למודעות שאוחזר מנגן הווידאו או מהתראה מהשרת. בדף Method: pod manifest מפורטות הדרישות של הפרמטרים האלה.

הפעלת המניפסט של רצף המודעות

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

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

דיווח על חשיפות ועל אירועי מודעות

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