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

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

    python -m http.server 8000

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

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

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

קודם כל, משנים את 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 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.