דף זה תורגם על ידי Cloud Translation API.

תחילת העבודה עם 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.

באמצעות שורת פקודה, מהספרייה שמכילה את הקובץ index.html מריצים את:
```
python -m http.server 8000
```
הערה: http.server זמין רק ב-Python 3.x.
בדפדפן אינטרנט, עוברים אל 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. ה-builder לוקח רכיב של וידאו, והמופע שנוצר לוקח רכיב של ממשק המשתמש של המודעה כדי לטפל בקליקים על המודעות.

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