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

ערכות ה-SDK של IMA מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות שלכם. ערכות IMA SDK יכולות לבקש מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את הפעלת המודעות באפליקציות שלכם. באמצעות ערכות ה-SDK של IMA DAI, האפליקציות שולחות בקשה לשידור של מודעת וידאו ותוכן וידאו – 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 טוען יחסי תלות באמצעות אותו פרוטוקול כמו הדף שממנו היא נטענת, עליכם להשתמש בשרת אינטרנט כדי לבדוק את האפליקציה. א' הדרך המהירה להפעלת שרת פיתוח מקומי היא להשתמש השרת.

  1. משורת הפקודה, בתיקייה שמכילה את הקובץ index.html, מריצים את הפקודה:

    python -m http.server 8000

  2. בדפדפן אינטרנט, עוברים אל http://localhost:8000/

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

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

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

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.