הגדרת IMA SDK ל-DAI

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

בחירת פתרון ה-DAI הרצוי

שירות DAI מלא

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

סקירה כללית על הטמעת מודעות דינמיות (DAI) ב-IMA

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

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

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

  • שלושה קבצים ריקים
    • 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 באמצעות תג סקריפט ב-dai.html, לפני התג של dai.js.

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

איך מפעילים את StreamManager

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

/**
 * 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, צריך להפעיל את השיטה 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.

ניתוח המטא-נתונים של השידור (שידור חי בלבד)

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

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Only used in LIVE streams. 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.