תחילת העבודה עם IMA DAI SDK

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

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

יצירת נגן וידאו פשוט

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

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA DAI SDK DAI Demo (HLS.JS)</h2>
    <video id="video"></video>
    <div id="ad-ui"></div>
</body>
</html>

dai.css

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

#ad-ui {
  cursor: pointer;
}

dai.js

var BACKUP_STREAM =
    'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'

// Livestream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

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

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;
var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

טעינת IMA DAI SDK

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

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>

אתחול ה-StreamManager ושליחת בקשה לשידור

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

לאחר מכן מגדירים פונקציות שמבקשות סטרימינג. הדוגמה הזו כוללת פונקציות גם ל-VOD וגם לשידורים חיים, שיוצרות מופעים של VODStreamRequest ו-LiveStreamRequest, בהתאמה, ואז קריאה לפונקציה streamManager.requestStream() עם הפרמטרים streamRequest. בשידורים חיים, צריך גם להוסיף handler כדי להאזין לאירועי מטא-נתונים מתוזמנים ולהעביר את האירועים אל StreamManager. אפשר להוסיף תגובה לקוד או לבטל את הוספת ההערה שהוא יתאים לתרחיש לדוגמה שלכם. שתי שיטות ההוספה משתמשות במפתח API אופציונלי. אם אתם משתמשים בשידור מוגן, צריך ליצור מפתח אימות של DAI.

אף אחד מהשידורים בדוגמה הזו לא מוגן, ולכן לא נעשה שימוש ב-apiKey.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  // Timed metadata is only used for LIVE streams.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in the metadata, 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);
      });
    }
  });

  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, null);
  // Uncomment the line below and comment out the one above to request a
  // LIVE stream instead of a VOD stream.
  //requestLiveStream(TEST_ASSET_KEY, null);
}

function requestVODStream(cmsId, videoId, apiKey) {
  var streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

function requestLiveStream(assetKey, apiKey) {
  var streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

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

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

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

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

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);

  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.LOADED,
     google.ima.dai.api.StreamEvent.Type.ERROR,
     google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
     google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
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');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

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();
  });
}

function onStreamPause() {
  console.log('paused');
  if (isAdBreak) {
    videoElement.controls = true;
    adUiElement.style.display = 'none';
  }
}

function onStreamPlay() {
  console.log('played');
  if (isAdBreak) {
    videoElement.controls = false;
    adUiElement.style.display = 'block';
  }
}

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