שימוש בשילוב מותאם אישית

לפני שמתחילים

המסמך הזה מתייחס רק להוראות ההפעלה במקרים שבהם לא נעשה שימוש ב-IMA DAI SDK.

לפני שממשיכים, צריך לוודא שכבר השלמתם את השלבים במאמר בנושא שילוב של Google Ad Manager‏ (GAM) עם נכסי VOD.

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

כדי לעשות את זה, תצטרכו את הפרטים הבאים:

Location האזור ב-Google Cloud שבו נוצר קובץ ההגדרות הפעיל:
LOCATION
מספר הפרויקט מספר הפרויקט בענן של Google Cloud שבו נעשה שימוש ב-Video Stitcher API:
PROJECT_NUMBER
טוקן OAuth אסימון OAuth לטווח קצר של חשבון שירות עם תפקיד המשתמש Video Stitcher: 
OAUTH_TOKEN
מידע נוסף על יצירת אסימוני OAuth לזמן קצר
הקוד של הרשת קוד הרשת ב-Ad Manager לשליחת בקשות להצגת מודעות:
NETWORK_CODE
מזהה ההגדרה של VOD מזהה ההגדרה של ה-VOD שציינתם כשיצרתם את אירוע השידור של ה-VOD:
VOD_CONFIG_ID

שליחת בקשה לרישום סטרימינג ל-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 מלאה לאימות מדיה נוצרת על ידי הוספה של מזהה אירוע של מודעה לכתובת הבסיסית הזו. MEDIA_VERIFICATION_URL
metadata_url כתובת ה-URL לבקשת מטא-נתונים של רצף מודעות. METADATA_URL
stream_id המחרוזת שמשמשת לזיהוי סשן הסטרימינג הנוכחי. 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/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

דוגמה לתשובה

{
  "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 ומאחסנים את הערכים הרלוונטיים.

יצירת סשן VOD של Cloud Video Stitcher

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

נקודת קצה ל-API

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

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

PROJECT_NUMBER מספר הפרויקט ב-Google Cloud.
LOCATION האזור שלכם ב-Google Cloud.
NETWORK CODE הקוד של הרשת שלכם ב-Google Ad Manager 360.

פרמטרים של תוכן הבקשה בקידוד JSON

vodConfig מחרוזת שמכילה את מספר הפרויקט, המיקום ומזהה הגדרות ה-VOD בפורמט הבא:
projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
adTracking מגדירים את הערך "CLIENT" כדי להפעיל מעקב בצד הלקוח.
gamSettings אובייקט שמכיל את הקוד של הרשת ואת מזהה הסטרים בפורמט הבא: 
{
  "networkCode":"NETWORK_CODE",
  "streamId":"STREAM_ID"
}

תגובת JSON

name השם של סשן ה-VOD, שמכיל את מזהה הסשן.
playUri ה-URI של מניפסט השידור המחובר, לטעינה בנגן הווידאו לצורך הפעלה.
SESSION_PLAYBACK_URI
adTracking אותו ערך adTracking שנשלח אל ה-API בגוף הבקשה.
vodConfig אותו מחרוזת vodConfig שנשלחה אל ה-API בגוף הבקשה.
gamSettings אותו אובייקט gamSettings שנשלח אל ה-API בגוף הבקשה.

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

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

דוגמה לתשובה

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

אחרי קבלת התשובה, אפשר להפעיל את השידור החי עם המודעות המחוברות על ידי הפניה ל-URI מהשדה playUri של אובייקט התשובה.

שליחת בקשה למטא-נתונים של רצפי מודעות מ-Ad Manager

שולחים בקשת GET ל-metadata_url שקיבלתם כשנרשמתם לשימוש בסטרימינג ב-Ad Manager. השלב הזה צריך להתבצע אחרי שמקבלים את מניפסט ה-stitched מ-URI של הפעלת התוכן.

בתמורה, מקבלים אובייקט JSON שמתאר את ההפסקות למודעות, המודעות והאירועים שקשורים למודעות בשידור.

נקודת קצה ל-API

GET: METADATA_URL
Host: dai.google.com

תגובת JSON

tags קבוצה של צמדי מפתח/ערך שמתארים אירועים של מדיה בפרסומות שיתרחשו בסטרימינג. כל מפתח מורכב מ-17 התווים הראשונים של מזהה מדיה של מודעה שיופיע במטא-נתונים של ID3 של הסטרים, או, במקרה של אירועי progress, ממזהה המדיה המלא של המודעה. כל ערך הוא אובייקט עם המאפיינים הבאים:
  • ‫ad: המזהה של המודעה שמכילה את אירוע המדיה של המודעה.
  • ‫ad_break_id: המזהה של ההפסקה למודעה שמכילה את אירוע המדיה של המודעה.
  • ‫type: סוג אירוע המדיה של המודעה. הערכים האפשריים הם:
    • ‫start – המודעה התחילה
    • ‫firstquartile – המודעה הושלמה ב-25%.
    • ‫midpoint – היצירה של המודעה הושלמה ב-50%.
    • ‫thirdquartile – המודעה הושלמה ב-75%.
    • ‫complete – המודעה הסתיימה.
    • ‫progress – מופעלת כל שנייה בזמן שהמודעה מוצגת.
ads קבוצה של צמדי מפתח/ערך שמתארים מודעות שיוצגו בתוך הסטרימינג. כל מפתח הוא מזהה מודעה. כל ערך הוא אובייקט עם המאפיינים הבאים:
  • ‫ad_break_id: המזהה של ההפסקה למודעה שמכילה את אירוע המדיה של המודעה.
  • ‫position: המיקום של המודעה בהפסקה למודעה. חשוב לדעת שהמיקום של המודעה הראשונה בהפסקה הוא 1.
  • ‫duration: משך המודעה בשניות, בפורמט של מספר נקודה צפה.
  • ‫title: הכותרת של המודעה, כפי שהיא מוגדרת ב-VAST.
  • ‫description: תיאור המודעה, כפי שמוגדר ב-VAST.
  • ‫ad_system: מערכת המודעות, כפי שמוגדרת ב-VAST.
  • ‫ad_system: מזהה המודעה, כפי שמוגדר ב-VAST.
  • ‫ad_system: מזהה הקריאייטיב, כפי שמוגדר ב-VAST.
  • ‫clickthrough_url: כתובת ה-URL שנפתחת כשמשתמש מקיים אינטראקציה עם המודעה.
  • ‫universal_ad_id: אובייקט שמייצג את מזהה המודעה האוניברסלי, כפי שמוגדר ב-VAST.
ad_breaks קבוצה של צמדי מפתח/ערך שמתארים את ההפסקות לפרסומות שיוצגו בשידור. כל מפתח הוא מזהה של הפסקה למודעה. כל ערך הוא אובייקט עם המאפיינים הבאים:
  • ‫type: סוג ההפסקה למודעה. הערכים יהיו אחד מהבאים:
    • ‫pre: מייצג מודעה לפני סרטון (pre-roll).
    • ‫mid: מייצג מודעה באמצע סרטון.
    • ‫post: מייצג מודעה בסוף הסרטון.
  • ‫duration: משך ההפסקה למודעה בשניות, כמספר נקודה צפה.
  • ‫expected_duration: משך הזמן הצפוי של ההפסקה למודעה בשניות, בפורמט נקודה צפה.
  • ‫ads: מספר המודעות בהפסקה למודעות.

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

curl METADATA_URL

דוגמה לתגובת JSON

{
  "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
    },
    ...
  }
}

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

האזנה לאירועי ID3 ומעקב אחרי אירועי הפעלה

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

  1. אחסון אירועי המדיה בתור, ושמירת כל מזהה מדיה יחד עם חותמת הזמן שלו, אם הוא מוצג על ידי נגן המדיה.
  2. בכל עדכון זמן מהנגן או בתדירות מוגדרת (מומלץ 500 אלפיות השנייה), בודקים את תור אירועי המדיה כדי לראות אילו אירועים הושמעו לאחרונה על ידי השוואת חותמות הזמן של האירועים למיקום הנוכחי.
  3. לאירועי מדיה שאתם מאשרים שהם הופעלו, בודקים את הסוג על ידי חיפוש מזהה המדיה בתגי הפסקות הפרסום המאוחסנים. חשוב לזכור שאובייקט התגים של הפסקת הפרסום מכיל רק גרסה קטומה של מזהה המדיה, שמוגבלת ל-10 הספרות הראשונות אחרי הקידומת google_, ולכן אין התאמה ישירה בין מזהי אימות המדיה של ID3 לבין המפתחות באובייקט התגים. הסיבה לכך היא כדי למנוע שליחה של פינגים לאימות אירועים לפני שהאירוע ID3 מגיע. כדי ליצור את כתובת ה-URL המלאה לאימות מדיה של אירוע שקשור למודעה, מוסיפים את מזהה האירוע המלא שקשור למודעה לערך media_verification_url מהתגובה ליצירת הסטרימינג.
  4. משתמשים באירועי 'התקדמות' כדי לעקוב אחרי משתמשים שנמצאים בהפסקה למודעה. כדי להימנע מקוד שגיאת HTTP, אל תשלחו את האירועים האלה לנקודת הקצה של אימות המדיה. לסוגי אירועים אחרים, מוסיפים את מזהה המדיה לכתובת ה-URL של אימות המדיה ושולחים בקשת GET כדי לעקוב אחרי ההפעלה.
  5. מסירים את אירוע המדיה מהתור.

נקודת קצה ל-API

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

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

MEDIA_VERIFICATION_URL הערך שמוחזר על ידי נקודת הקצה של רישום הזרם, בשדה media_verification_url:
MEDIA_VERIFICATION_URL
AD_MEDIA_ID המזהה המלא של מדיה המודעה, כפי שהוא מופיע במטא-נתונים של ID3 בסטרימינג:
AD_MEDIA_ID

ערכי החזרה צפויים

HTTP/1.1 204 No Content תגובה ריקה מוצלחת.
HTTP/1.1 404 Not Found מזהה אימות המדיה לא זוהה.
HTTP/1.1 409 Conflict מזהה אימות המדיה כבר נשלח.

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

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

דוגמה לתשובה

HTTP/1.1 204 No Content

מגבלות

אם משתמשים ב-API בתצוגות אינטרנט, ההגבלות הבאות חלות על טירגוט:

  • ‫UserAgent: פרמטר סוכן המשתמש מועבר כערך ספציפי לדפדפן במקום כפלטפורמה הבסיסית.
  • ‫rdid, ‏ idtype, ‏ is_lat: מזהה המכשיר לא מועבר בצורה תקינה, ולכן יש מגבלות על הפונקציונליות של התכונות הבאות:
    • מכסת תדירות
    • סבב מודעות ברצף
    • פילוח קהל וטירגוט
הבא
סקירה כללית