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

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

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

איך בוחרים את פתרון DAI שמעניין אתכם

הצגת מודעות דינמיות (DAI) ב-Pod

במדריך הזה מוסבר איך להפעיל שידור חי או ב-VOD של הצגת פודקאסטים ב-DAI. באמצעות IMA DAI SDK ל-HTML5 עם נגן וידאו שמסתמך על hls.js להפעלה. אם אתם רוצים להציג טעימה מלאה או לעקוב אחריו בשילוב עם תמיכה ב-HLS.js ובהפעלה ב-Safari, דוגמה למילוי בקשות של pod HLS. לתמיכה ב-DASH.js, ראו דוגמה להצגת Pod של DASH. אפשר להוריד את האפליקציות לדוגמה האלה מגרסת HTML5 DAI GitHub .

סקירה כללית – הצגת מודעות Pod ב-DAI

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

PodStreamRequest / PodVodStreamRequest: אובייקט שמגדיר בקשת סטרימינג לשרתים של Google לפרסום. הבקשות מציינות קוד רשת. הפרמטר PodStreamRequest מחייב גם מפתח נכס מותאם אישית, ואופציונלי API key. שתי הפונקציות כוללות פרמטרים אופציונליים אחרים.
StreamManager: אובייקט שמטפל בתקשורת בין הסטרימינג של הווידאו ו-IMA DAI SDK, כמו הפעלת פינגים של מעקב. להעביר אירועים בסטרימינג לבעל התוכן הדיגיטלי.

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

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

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

הגדרת סביבת פיתוח

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

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

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

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

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

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

הקבועים של בקשות הסטרימינג הם:

BACKUP_STREAM: כתובת URL של שידור לגיבוי, שיופעל במקרה של עיבוד המודעות מקבל שגיאה חמורה.
STREAM_URL: משמש רק בשידורים חיים. כתובת ה-URL של הווידאו בסטרימינג סופקה על ידי הכלי לניהול המניפסט או שותף הצד השלישי שמשתמשים בו כדי להציג Pod. לפני שליחת הבקשה, תתבקשו להזין את מזהה הסטרימינג שסופק על ידי IMA DAI SDK. במקרה הזה, כתובת ה-URL של השידור כוללת placeholder, [[STREAMID]], שמוחלף במזהה מקור הנתונים לפני שליחת בקשה.
NETWORK_CODE: קוד הרשת של חשבון Ad Manager 360.
CUSTOM_ASSET_KEY: משמש רק לשידורים חיים. מפתח הנכס המותאם אישית שמזהה את אירוע הצגת המודעות של הרצף ב-Ad Manager 360. אפשר ליצור את זה על ידי הכלי לניהול המניפסט או שותף הצגת ה-Pod של צד שלישי.
API_KEY: משמש רק לשידורים חיים. מפתח API אופציונלי שעשוי להידרש כדי לאחזר מזהה של שידור מ-IMA DAI SDK.

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 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'

// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";

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

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

טעינת IMA DAI SDK

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

הצגת מודעות ברצף של שידורים חיים

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

לאחר מכן, מגדירים פונקציה לבקשת ה-Pod שמציג את השידור החי. הפונקציה הזו קודם יוצר PodStreamRequest, מגדיר אותו באמצעות StreamRequest שצוינו בשלב 2, ואז קוראת ל-streamManager.requestStream() עם אובייקט הבקשה הזה.

dai.js

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

  requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}

function requestLivePodStream(networkCode, customAssetKey, apiKey) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving live Stream Request
  const streamRequest = new google.ima.dai.api.PodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.apiKey = apiKey;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

מילוי בקשות Pod של VOD

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

לאחר מכן מגדירים פונקציה שמבקשת את ה-pod שמציג את שידור ה-VOD. הפונקציה הזו קודם יוצר PodVodStreamRequest, מגדיר אותו באמצעות StreamRequest שצוינו בשלב 2, ואז קוראת ל-streamManager.requestStream() עם אובייקט הבקשה הזה.

dai.js

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

  requestVodPodStream(NETWORK_CODE);
}

function requestVodPodStream(networkCode) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving VOD Stream Request
  const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

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

הצגת פודקאסטים בשידור חי

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

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    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.STREAM_INITIALIZED:
      console.log('Stream initialized');
      loadStream(e.getStreamData().streamId);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream('');
      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 loadStream(streamID) {
  var url;
  if(streamID) {
    url = STREAM_URL.replace('[[STREAMID]]', streamID);
  } else {
    console.log('Stream Initialization Failed');
    url = BACKUP_STREAM;
  }
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
}

הצגת מודעות ב-POD של VOD

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

בנוסף, כדי להפעיל את ההעברה של מודעות VOD במודעות וידאו, צריך להפעיל את StreamManager.loadStreamMetadata() בתגובה לאירוע STREAM_INITIALIZED. צריך גם לבקש את כתובת ה-URL של השידור שותף טכנולוגיית וידאו (VTP). אחרי שהקריאה ל-loadStreamMetadata() תצליח, היא תפעיל אירוע LOADED, שבו צריך להפעיל פונקציית loadStream() עם כתובת ה-URL של השידור כדי לטעון את השידור ולהפעיל אותו.

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    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.STREAM_INITIALIZED:
      const streamId = e.getStreamData().streamId;
      // 'vtpInterface' is a place holder for your own video technology
      //  partner (VTP) API calls.
      vtpInterface.requestStreamURL({
        'streamId': streamId,
      })
      .then( (vtpStreamUrl) => {
        streamUrl = vtpStreamUrl;
        streamManager.loadStreamMetadata();
      }, (error) => {
        // Handle the error.
      });
      break;
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      loadStream(streamUrl);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream();
      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 loadStream(url) {
  if(url) {
    console.log('Loading:' + url);
    hls.loadSource(url);
  } else {
    console.log('Stream Initialization Failed');
    hls.loadSource(BACKUP_STREAM);
  }
  hls.attachMedia(videoElement);
}

טיפול במטא-נתונים של שידורים חיים

בשלב הזה מטמיעים פונקציות event listener למטא-נתונים שיודיעו ל-SDK כאשר ואירועי מודעות מתרחשים. ההאזנה לאירועי מטא-נתונים של מודעת וידאו In-stream עשויה להשתנות בהתאם פורמט הסטרימינג (HLS או DASH), סוג השידור (שידור חי או VOD), סוג הנגן וסוג הקצה העורפי של DAI שבו נעשה שימוש. אפשר לעיין בפריטים מתוזמנים מטא-נתונים לקבלת מידע נוסף.

פורמט של שידור HLS (שידורים חיים ושידורי VOD, נגן HLS.js)

אם משתמשים בנגן HLS.js, מאזינים ל: האירוע FRAG_PARSING_METADATA של HLS.js כדי לקבל את המטא-נתונים של ID3 ולהעביר אותם אל SDK עם StreamManager.processMetadata().

כדי להפעיל את הסרטון באופן אוטומטי אחרי שהכול נטען ומוכן, צריך להאזין לאירוע MANIFEST_PARSED של HLS.js כדי להפעיל את ההפעלה.

function loadStream(streamID) {
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  
  // Timed metadata is passed HLS stream events to the streamManager.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
  hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}

function parseID3Events(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((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
}

function startPlayback() {
  console.log('Video Play');
  videoElement.play();
}

DASH.js (פורמט של שידורי DASH, סוג של שידור חי ו-VOD)

אם אתם משתמשים בנגן DASH.js, עליכם להשתמש במחרוזות שונות כדי להאזין למטא-נתונים של ID3 בסטרימינג בשידור חי או בסטרימינג של VOD:

שידורים חיים: 'https://developer.apple.com/streaming/emsg-id3'
שידורי VOD: 'urn:google:dai:2018'

מעבירים את המטא-נתונים של ה-ID3 ל-SDK באמצעות StreamManager.processMetadata().

כדי להציג את פקדי הווידאו באופן אוטומטי אחרי שכל הנתונים נטענו והסרטון מוכן, צריך להאזין לאירוע MANIFEST_LOADED ב-DASH.js.

const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);

function processMetadata(metadataEvent) {
  const messageData = metadataEvent.event.messageData;
  const timestamp = metadataEvent.event.calculatedPresentationTime;

  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with dash.js.
  streamManager.processMetadata('ID3', messageData, timestamp);
}

function loadlistener() {
  showControls();

  // This listener must be removed, otherwise it triggers as addional
  // manifests are loaded. The manifest is loaded once for the content,
  // but additional manifests are loaded for upcoming ad breaks.
  dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}

נגן Shaka עם שידורים חיים (פורמט של שידורי DASH)

אם אתם משתמשים ב-Shaka Player להפעלת שידורים חיים, תוכלו להשתמש במחרוזת 'emsg' כדי להאזין לאירועי מטא-נתונים. לאחר מכן, משתמשים בנתוני ההודעה של האירוע בקריאה ל-StreamManager.onTimedMetadata().

shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));

function onEmsgEvent(metadataEvent) {
  // Use StreamManager.onTimedMetadata() if your video player provides
  // processed metadata, as with Shaka player livestreams.
  streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}

נגן Shaka עם שידורי VOD (פורמט שידורי DASH)

אם אתם משתמשים ב-Shaka Player להפעלת שידורי VOD, תוכלו להשתמש במחרוזת 'timelineregionenter' כדי להאזין לאירועי מטא-נתונים. אחר כך משתמשים בנתוני ההודעות מהאירועים בשיחה כדי StreamManager.processMetadata() עם המחרוזת 'urn:google:dai:2018'.

shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));

function onTimelineEvent(metadataEvent) {
  const detail = metadataEvent.detail;
  if ( detail.eventElement.attributes &&
       detail.eventElement.attributes['messageData'] &&
       detail.eventElement.attributes['messageData'].value ) {
        const mediaId = detail.eventElement.attributes['messageData'].value;
        const pts = detail.startTime;
        // Use StreamManager.processMetadata() if your video player provides raw
        // ID3 tags, as with Shaka player VOD streams.
        streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
       }
}

טיפול באירועי שחקן

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

function loadStream(streamUrl) {
  ...
  
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);
}

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