הגדרת 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>


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

#adUi {
  cursor: pointer;
}

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

dai.css
 
// 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';
  });
}
dai.js

כדי להמשיך את ההפעלה במהלך הפסקות הפרסום שהושהו, צריך להגדיר מאזיני אירועים לאירועים 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';
}
dai.js

טעינת IMA DAI SDK

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

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

הפעלת StreamManager

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

/**
 * 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);
}
dai.js

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

הגדרת פונקציות לבקשת סטרימינג. הדוגמה הזו כוללת פונקציות גם ל-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);
}
dai.js

שתי השיטות לשליחת בקשות לשידור מקבלות מפתח 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);
      });
    }
  });
}
dai.js

במדריך הזה נעשה שימוש בנגן 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();
  });
}
dai.js

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

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