הגדרת IMA SDK ל-DAI

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

ערכות IMA SDK מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות. ‫IMA SDKs יכולים לשלוח בקשות למודעות מכל שרת מודעות שתואם ל-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

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