הגדרת IMA SDK ל-DAI

ערכות IMA SDK מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות. ‫IMA SDKs יכולים לשלוח בקשות למודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות. באמצעות IMA DAI SDK, האפליקציות שולחות בקשה לסטרימינג של מודעות ותוכן וידאו – תוכן VOD או תוכן בשידור חי. לאחר מכן, ה-SDK מחזיר זרם וידאו משולב, כך שלא צריך לנהל את המעבר בין מודעה לתוכן וידאו באפליקציה.

בחירת פתרון DAI שמעניין אתכם

Full service Pod serving Cloud stitching API Live Cloud stitching API VOD

הפעלת שידורים חיים שנרשמו באמצעות Google Cloud Video Stitcher API

במדריך הזה מוסבר איך להשתמש ב-IMA DAI SDK ל-HTML5 כדי לשלוח בקשה להפעלה של שידור חי של אירוע שנרשם ב-Google Cloud Video Stitcher API, ואיך להוסיף הפסקת פרסום במהלך ההפעלה.

המדריך הזה מרחיב את הדוגמה הבסיסית מהמדריך למתחילים בנושא IMA DAI.

מידע על שילוב עם פלטפורמות אחרות או על שימוש ב-IMA SDKs בצד הלקוח זמין במאמר Interactive Media Ads SDKs.

כדי לראות או לעקוב אחרי שילוב לדוגמה שהושלם, מורידים את הדוגמה של Cloud Video Stitcher ל-HLS או ל-DASH.

הערה: ‫IMA DAI SDK ל-HTML5 תומך בסטרימינג של HLS ו-DASH, אבל כדי להפעיל כל אחד מהם צריך נגן מדיה או תוסף שונים, כמו HLS.js או DASH.js, עם הטמעות שונות.

במדריך הזה מוסבר איך להגדיר את HLS.js ואת IMA DAI SDK כדי להפעיל שידור HLS, עם הערות חשובות לגבי הבדלים בהטמעה של DASH.

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

הגדרת פרויקט ב-Google Cloud

מגדירים פרויקט ב-Google Cloud ומגדירים חשבונות שירות כדי לגשת לפרויקט.

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

מזינים את המשתנים הבאים לשימוש ב-IMA SDK:

מיקום

האזור ב-Google Cloud שבו נוצרת ההגדרה הפעילה: LOCATION

מספר הפרויקט

מספר הפרויקט ב-Google Cloud שבו נעשה שימוש ב-Video Stitcher API: PROJECT_NUMBER

טוקן OAuth

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

OAUTH_TOKEN

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

קוד רשת

קוד הרשת ב-Ad Manager לשליחת בקשות להצגת מודעות: NETWORK_CODE

מזהה ההגדרה של שידור חי

מזהה ההגדרה של השידור החי שציינתם כשייצרתם את האירוע בשידור חי: LIVE_CONFIG_ID

מפתח של נכס מותאם אישית

מפתח הנכס המותאם אישית של Ad Manager שנוצר במהלך יצירת הגדרה לאירוע בשידור חי באמצעות Video Stitcher API: CUSTOM_ASSET_KEY

הגדרת סביבת פיתוח

נקודה חשובה: המחלקה VideoStitcherLiveStreamRequest של IMA DAI תומכת בסטרימינג של HLS ובסטרימינג של DASH עם כמה תקופות. הפסקות הפרסום מוכנסות רק בין תקופות DASH.

אפליקציות לדוגמה של IMA מדגימות רק בקשות לסטרימינג של HLS. עדיין אפשר להשתמש בזרמי DASH כשיוצרים את המחלקה VideoStitcherLiveStreamRequest. כשמגדירים נגן שתואם ל-DASH, צריך להגדיר מאזין לאירועי ההתקדמות של נגן הווידאו, שיכול לספק את המטא-נתונים של הסרטון ל-StreamManager.processMetadata(). הפונקציה הזו מקבלת שלושה פרמטרים:

1. ‫type: מחרוזת שצריך להגדיר לה את הערך 'ID3' לשידורים בפרוטוקול HLS ואת הערך 'urn:google:dai:2018' לשידורים בפרוטוקול DASH.

2. ‫data: עבור הודעות אירועים ב-DASH, זו מחרוזת נתוני ההודעה.

3. ‫timestamp: מספר שמייצג את זמן ההתחלה של הודעת האירוע בסטרימינג בפורמט DASH.

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

מורידים את הדוגמאות של IMA DAI ל-HTML5 ומחלצים את הדוגמה הפשוטה של HLS.js לתיקייה חדשה. הדוגמה הזו היא אפליקציית אינטרנט שאפשר לארח באופן מקומי למטרות בדיקה.

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

python3 -m http.server 8000

הפונקציה http.server זמינה רק ב-Python 3.x. אפשר להשתמש בכל שרת אינטרנט אחר, כמו Apache HTTP Server או Node JS.

פותחים דפדפן אינטרנט ועוברים אל localhost:8000 כדי לראות נגן וידאו. הדפדפן צריך לתמוך בספריית HLS.js.

אם הכול פועל כמו שצריך, לחיצה על לחצן ההפעלה בנגן הווידאו תתחיל את הסרט הקצר Tears of Steel (דמעות מפלדה) אחרי מודעה קצרה. התוכן הזה מועבר באמצעות סטרימינג של וידאו על פי דרישה (VOD).

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

כדי להחליף את זרם ה-VOD לדוגמה בשידור החי שלכם, משתמשים במחלקה VideoStitcherLiveStreamRequest שיוצרת באופן אוטומטי סשן של מודעות ב-Google Ad Manager. אתם יכולים להשתמש בממשק המשתמש של Google Ad Manager כדי לאתר את סשני ה-DAI שנוצרו לצורך מעקב וניפוי באגים.

בדוגמה הקיימת יש פונקציות לבקשת סטרימינג של VOD או של שידור חי. כדי שהפונקציה תפעל עם Google Cloud Video Stitcher API, צריך להוסיף פונקציה חדשה שתחזיר אובייקט VideoStitcherLiveStreamRequest.

לדוגמה:

// StreamManager which will be used to request ad-enabled streams.
let streamManager;
...
function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(
    videoElement,
    adUiElement
  );
  streamManager.addEventListener(
      [
        google.ima.dai.api.StreamEvent.Type.LOADED,
        google.ima.dai.api.StreamEvent.Type.ERROR,
        google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
        google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED
      ],
      onStreamEvent, false);

  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  videoElement.addEventListener('pause', () => {
    playButton.style.display = 'block';
  });

  playButton.addEventListener('click', initiatePlayback);
}

function initiatePlayback() {
  requestVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...

function requestVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest();
  streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';
  streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY';

  streamManager.requestStream(streamRequest);
}

לצורך בדיקה מקומית, אם קובצי השידור החי נמצאים בקטגוריה של Cloud Storage, צריך להפעיל CORS למקור http://localhost:8000.

טוענים מחדש את הדף. לאחר מכן תוכלו לבקש ולהפעיל שידורים חיים בהתאמה אישית.

(אופציונלי) מוסיפים אפשרויות של סשן סטרימינג

אפשר להתאים אישית את בקשת הסטרימינג על ידי הוספת אפשרויות הפעלה כדי לשנות את הגדרת ברירת המחדל של Cloud Video Stitcher API באמצעות VideoStitcherLiveStreamRequest.videoStitcherSessionOptions. אם תספקו אפשרות לא מזוהה, Cloud Video Stitcher API יגיב עם שגיאת HTTP 400. אפשר לקבל עזרה במדריך לפתרון בעיות.

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

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);

הוספת הפסקה למודעה

ממשק ה-API של Google Cloud Video Stitcher מוסיף מודעות שאוחזרו מתג המודעה לכל הפסקה לפרסומות. הפסקות הפרסום מסומנות במניפסט באמצעות סמני פרסום. סמני המודעות מוכנסים על ידי המקודד של השידור החי.

• אם אתם משתמשים בשידור חי משלכם, אתם צריכים להוסיף את סמן המודעה. מידע נוסף על סמני המודעות הנתמכים ב-HLS וב-DASH זמין במאמרי העזרה בנושא סמני מודעות.

• אם יצרתם שידור חי באמצעות Google Cloud Livestream API, אתם יכולים להוסיף אירוע של הפסקת פרסום בערוץ.

המודעה מוצגת מיד אחרי שההפסקה למודעות מוכנסת.

הסרת המשאבים

אחרי שסיימתם לארח שידור חי באמצעות Google Cloud Video Stitcher API ולבקש אותו באמצעות IMA DAI SDK ל-HTML5, חשוב לנקות את כל משאבי הצגת המודעות.

כדי להסיר משאבים ונכסים מיותרים, פועלים לפי המדריך בנושא מחיקת משאבים של שידור חי.

לבסוף, בחלון הטרמינל שבו הפעלתם את שרת האינטרנט של Python 3, משתמשים בפקודה ctrl+C כדי לסיים את השרת המקומי.