הגדרה עם DAI בשירות מלא

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

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

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

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

  • ‫ StreamRequest – VODStreamRequest או LiveStreamRequest: אובייקט שמגדיר בקשה לשידור. הבקשות לשידור יכולות להיות לווידאו על פי דרישה (VOD) או לשידורים חיים. בבקשות לשידור חי מציינים מפתח נכס, ובבקשות ל-VOD מציינים מזהה CMS ומזהה סרטון. שני סוגי הבקשות יכולים לכלול מפתח API שנדרש כדי לגשת לסטרימים שצוינו, וקוד רשת של Google Ad Manager כדי ש-IMA SDK יטפל במזהי מודעות כפי שצוין בהגדרות של Google Ad Manager.
  • StreamManager: אובייקט שמטפל בסטרימינג של הטמעת מודעות דינמיות ובאינטראקציות עם הקצה העורפי של 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);
}

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

מגדירים פונקציות לבקשת שידורים. הדוגמה הזו כוללת פונקציות גם לווידאו על פי דרישה וגם לשידורים חיים, שיוצרות מופעים של המחלקה 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.