הגדרת IMA SDK ל-DAI

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

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

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

DAI בשירות מלא

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

סקירה כללית על IMA DAI

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

  • ‫ StreamRequest – VODStreamRequest או LiveStreamRequest: אובייקט שמגדיר בקשה לשידור. בקשות לשידור יכולות להיות לווידאו על פי דרישה או לשידורים חיים. בבקשות לשידור חי מציינים מפתח נכס, ובבקשות ל-VOD מציינים מזהה CMS ומזהה סרטון. שני סוגי הבקשות יכולים לכלול אופציונלית מפתח API שנדרש לגישה לסטרימינג שצוין, וקוד רשת של Google Ad Manager כדי ש-IMA SDK יטפל במזהי מודעות כמו שצוין בהגדרות של Google Ad Manager.
  • ‫ StreamManager: אובייקט שמטפל בסטרימינג של הטמעת מודעות דינמיות ובאינטראקציות עם ה-Backend של DAI. מנהל הסטרימינג מטפל גם בפינגים של מעקב ומעביר אירועים של סטרימינג ומודעות אל בעל התוכן הדיגיטלי.

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

  • שלושה קבצים ריקים
    • dai.html
    • dai.css
    • dai.js
  • ‫Python מותקן במחשב, או שרת אינטרנט לשימוש בבדיקות

הפעלת שרת פיתוח

‫IMA DAI SDK טוען תלות באמצעות אותו פרוטוקול כמו הדף שממנו הוא נטען, ולכן צריך להשתמש בשרת אינטרנט כדי לבדוק את האפליקציה. דרך מהירה להתחיל שרת פיתוח מקומי היא להשתמש בשרת המובנה של Python.

  1. משתמשים בשורת פקודה, מהספרייה שמכילה את הקובץ index.html, ומריצים את הפקודה:

    python -m http.server 8000

  2. בדפדפן אינטרנט, עוברים אל http://localhost:8000/

    אפשר גם להשתמש בכל שרת אינטרנט אחר, כמו Apache HTTP Server.

יצירת נגן וידאו

קודם כל, משנים את dai.html כדי ליצור רכיב וידאו HTML5 ורכיב div לשימוש בקליקים. בדוגמה הבאה מתבצע ייבוא של IMA DAI SDK. פרטים נוספים זמינים במאמר בנושא ייבוא של IMA DAI SDK.

בנוסף, מוסיפים את התגים הנדרשים כדי לטעון את הקבצים dai.css ו-dai.js, וכדי לייבא את נגן הווידאו hls.js. לאחר מכן, משנים את dai.css כדי לציין את הגודל והמיקום של רכיבי הדף. לבסוף, ב-dai.js, מגדירים משתנים שיכילו את פרטי בקשת הסטרימינג, פונקציה initPlayer() שתופעל כשהדף ייטען ומגדירים את לחצן ההפעלה כדי לבקש סטרימינג בלחיצה.

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>


#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}

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

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}

טעינת IMA DAI SDK

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

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>

הפעלת StreamManager

כדי לבקש קבוצה של מודעות, צריך ליצור ima.dai.api.StreamManager, שאחראי לבקשת סטרימינג של DAI ולניהול שלו. ה-constructor מקבל אלמנט וידאו ורכיב בממשק המשתמש של המודעה כדי לטפל בקליקים על המודעה.

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}

שליחת בקשה לסטרימינג

הגדרת פונקציות לבקשת סטרימינג. הדוגמה הזו כוללת פונקציות גם ל-VOD וגם לשידורים חיים, שיוצרות מופעים של המחלקה VODStreamRequest ושל המחלקה LiveStreamRequest. אחרי שיש לכם מכונת streamRequest, מבצעים קריאה ל-method‏ streamManager.requestStream() עם מופע של בקשת הסטרימינג.

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

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

ניתוח מטא-נתונים של שידור חי

צריך גם להוסיף handler להאזנה לאירועי מטא-נתונים מתוזמנים ולהעברת האירועים למחלקה StreamManager כדי ש-IMA ישדר אירועים של מודעות במהלך הפסקות הפרסום:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  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);
      });
    }
  });
}

במדריך הזה נעשה שימוש בנגן hls.js להפעלת הזרם, אבל ההטמעה של המטא-נתונים תלויה בסוג הנגן שבו אתם משתמשים.

טיפול באירועים בסטרימינג

מטמיעים פונקציות event listener לאירועים מרכזיים שקשורים לסרטונים. בדוגמה הזו, הטיפול באירועים LOADED, ERROR, AD_BREAK_STARTED ו-AD_BREAK_ENDED מתבצע על ידי קריאה לפונקציה onStreamEvent(). הפונקציה הזו מטפלת בטעינת הסטרימינג, בשגיאות בסטרימינג ובהשבתת כפתורי הנגן במהלך הפעלת המודעות, כפי שנדרש ב-IMA SDK.

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
function loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}

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

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