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

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

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

חשוב לוודא שכבר השלמתם את השלבים במאמר בנושא שילוב של Google Ad Manager‏ (GAM) עם שידורים חיים.

הערה: מומלץ מאוד להשתמש ב-IMA DAI SDK בפלטפורמות שבהן הוא נתמך.

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

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

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

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

שליחת בקשה לרישום סטרימינג ל-Ad Manager

שולחים בקשת POST לנקודת הקצה של רישום הסטרימינג. בתגובה, מקבלים קובץ JSON שמכיל את מזהה הסטרימינג שצריך לשלוח ל-API של שילוב הסרטונים.

נקודת קצה ל-API

POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

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

NETWORK_CODE	קוד הרשת שלכם ב-Google Ad Manager 360: NETWORK_CODE
CUSTOM_ASSET_KEY	המזהה המותאם אישית שמשויך לאירוע הזה ב-Google Ad Manager: CUSTOM_ASSET_KEY

פרמטרים של גוף הבקשה בקידוד טופס

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

תגובת JSON

media_verification_url	כתובת ה-URL הבסיסית לשליחת פינג לאירועי מעקב אחר הפעלה. כתובת URL מלאה לאימות מדיה נוצרת על ידי הוספה של מזהה אירוע של מודעה לכתובת הבסיסית הזו. MEDIA_VERIFICATION_URL
metadata_url	כתובת ה-URL לבקשת מטא-נתונים של רצף מודעות. METADATA_URL
polling_frequency	התדירות המומלצת באלפיות השנייה לבדיקה של `metadata_url`. POLLING_FREQUENCY
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/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

דוגמה לתשובה

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

במקרה של שגיאות, מוחזרים קודי שגיאה סטנדרטיים של HTTP ללא גוף תגובת JSON.

מנתחים את תגובת ה-JSON ומאחסנים את הערכים הרלוונטיים.

הערה: כתובות ה-URL שמופיעות בתגובת ה-API עשויות להשתנות ללא הודעה מוקדמת. לכן, כדאי להשתמש בכתובות ה-URL שמופיעות בתגובת ה-API במקום ליצור אותן בעצמכם. כך תוכלו לוודא שהקוד ימשיך לפעול בצורה תקינה גם כשכתובות ה-URL ישתנו.

יצירת URI של הפעלה של פעילות

שולחים בקשת POST לנקודת הקצה (endpoint) /livesessions של video stitcher API כדי ליצור סשן חדש של שידור חי. בתגובה, תקבלו תגובת JSON שמכילה את מניפסט הסטרימינג לטעינה בנגן הווידאו.

נקודת קצה ל-API

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

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

PROJECT_NUMBER	מספר הפרויקט בענן של Google Cloud שבו נעשה שימוש ב-Video Stitcher API: PROJECT_NUMBER
LOCATION	האזור ב-Google Cloud שבו נוצר קובץ ההגדרות הפעיל: LOCATION

פרמטר של כותרת הרשאה

OAUTH_TOKEN

אסימון OAuth לטווח קצר של חשבון שירות עם תפקיד המשתמש Video Stitcher: OAUTH_TOKEN

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

liveConfig	מחרוזת שמכילה את מספר הפרויקט, המיקום ומזהה ההגדרה של השידור החי בפורמט הבא: projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID
adTracking	מגדירים את הערך "CLIENT" כדי להפעיל מעקב בצד הלקוח.
gamSettings	אובייקט שמכיל את מזהה הסטרימינג בפורמט הבא: {"streamId":"STREAM_ID"}

תגובת JSON

name	השם של הסשן בשידור חי, שמכיל את מזהה הסשן.
playUri	ה-URI של מניפסט השידור המחובר, לטעינה בנגן הווידאו לצורך הפעלה. PLAY_URI
liveConfig	אותו מחרוזת liveConfig שנשלחה אל ה-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/liveSessions

request.json

{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
  "adTracking": "CLIENT",
  "gamSettings": {
    "streamId": "STREAM_ID"
  }
}

דוגמה לתשובה

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
  "playUri": PLAY_URI,
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
  "gamSettings": {
    "streamId": STREAM_ID
  }
}

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

‫Video Stitcher API יוצר מזהה סשן ייחודי לכל בקשה, שאפשר לאחזר מהקטע האחרון של השדה name של אובייקט התגובה.

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

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

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

חשוב: אל תיצרו בעצמכם את כתובת ה-URL של בקשת המטא-נתונים, כי הפורמט שלה עשוי להשתנות ללא הודעה מוקדמת. במקום זאת, צריך להשתמש בערך metadata_url שמוחזר מבקשת הרישום של הזרם.

בתמורה, מקבלים אובייקט 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 https://dai.google.com/.../metadata/

דוגמה לתשובה

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },
      ...
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/...",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },
      ...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "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: מזהה המכשיר לא מועבר בצורה תקינה, ולכן יש מגבלות על הפונקציונליות של התכונות הבאות:
  • מכסת תדירות
  • סבב מודעות ברצף
  • פילוח קהל וטירגוט