איך מתחילים לעבוד עם IMA SDK ל-DAI

בחירת פלטפורמה: HTML5 Android iOS tvOS Cast Roku

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

בוחרים את פתרון ה-DAI המועדף:

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

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

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

כדי לקבל מידע על שילוב עם פלטפורמות אחרות או על שימוש בערכות IMA SDK בצד הלקוח, עיינו במאמר Interactive Media Ads SDKs.

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

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

הגדרת פרויקט בענן ב-Google Cloud והגדרת חשבונות שירות כדי לגשת לפרויקט.

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

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

מיקום
האזור ב-Google Cloud שבו נוצר ה-live config: LOCATION
מספר הפרויקט
מספר הפרויקט בענן של Google שבו משתמשים ב-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

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

האפליקציות לדוגמה של 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);

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

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

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

הסרת המשאבים

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

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

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