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

שנתחיל?

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

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

סקירה כללית של IMA DAI

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

StreamRequest — VODStreamRequest או LiveStreamRequest: אובייקט שמגדיר בקשה לשידור. הבקשות לסטרימינג יכולות להיות על פי דרישה (VOD) או בשידור חי. בבקשות מצוין מזהה תוכן, כמו גם מפתח API או אסימון אימות ופרמטרים אחרים.
StreamManager: אובייקט שמטפל בסטרימינג דינמי של הטמעת מודעות ובאינטראקציות עם הקצה העורפי של DAI. מנהל השידור גם מטפל בפינגים של מעקב ומעביר אירועים של אירועים ומודעות למפרסם.

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

לפני שמתחילים, צריך:

שלושה קבצים ריקים
- dai.html
- dai.css
- dai.js
Python במחשב, או שרת אינטרנט לשימוש לבדיקה

1. הפעלת שרת פיתוח

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

בשורת הפקודה, מהספרייה שמכילה את הקובץ index.html:
```
python -m http.server 8000
```
הערה: http.server זמין רק ב-Python 3.x.
בדפדפן האינטרנט, יש לעבור אל http://localhost:8000/

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

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

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

// Live stream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2528370";
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');
}

3. טעינת ה-IMA 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>

...

4. מפעילים את StreamManager ושולחים בקשת שידור

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

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

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

5. ניהול אירועי סטרימינג

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

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

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