Pierwsze kroki z pakietem IMA DAI SDK

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą żądać reklam z dowolnego serwera reklam zgodnego z VAST i zarządzać odtwarzaniem reklam w Twoich aplikacjach. Dzięki pakietom IMA DAI aplikacje mogą wysyłać żądania strumienia w przypadku reklam i treści wideo (VOD lub na żywo). Pakiet SDK zwraca następnie połączony strumień wideo, dzięki czemu nie musisz zarządzać przełączaniem między reklamami wideo a treściami wideo w aplikacji.

Wybierz rozwiązanie DAI, które Cię interesuje

Kompleksowe funkcje DAI

W tym przewodniku pokazujemy, jak zintegrować pakiet IMA DAI SDK z prostą aplikacją odtwarzacza wideo. Jeśli chcesz wyświetlić ukończoną przykładową integrację lub wykonać jej instrukcje, pobierz prosty przykład z GitHuba.

Omówienie IMA DAI

Implementacja IMA DAI obejmuje 2 główne komponenty pakietu SDK, co pokazano w tym przewodniku:

  • StreamRequest – VODStreamRequest lub LiveStreamRequest: obiekt definiujący żądanie strumienia. Żądania strumienia mogą dotyczyć filmów na żądanie lub transmisji na żywo. Żądania określają identyfikator treści, a także klucz interfejsu API lub token uwierzytelniania i inne parametry.
  • StreamManager: obiekt, który obsługuje strumienie dynamicznego wstawiania reklam i interakcje z backendem DAI. Menedżer strumienia obsługuje też pingi śledzenia oraz przekazuje wydawcy strumień i zdarzenia reklamowe.

Wymagania wstępne

  • 3 puste pliki
    • dai.html
    • dai.css
    • dai.js
  • Python zainstalowany na komputerze lub serwer WWW do testowania

Uruchamianie serwera programistycznego

Pakiet IMA DAI SDK wczytuje zależności przy użyciu tego samego protokołu co strona, z której się wczytuje. Dlatego do przetestowania aplikacji musisz użyć serwera WWW. Najprostszym sposobem uruchomienia lokalnego serwera programistycznego jest użycie wbudowanego serwera Pythona.

  1. W wierszu poleceń otwórz katalog zawierający plik index.html:

    python -m http.server 8000

  2. W przeglądarce otwórz stronę http://localhost:8000/

    Możesz też użyć dowolnego innego serwera WWW, na przykład serwera HTTP Apache.

Utwórz prosty odtwarzacz wideo

Najpierw zmodyfikuj plik dai.html, by utworzyć prosty element wideo HTML5 i element div do śledzenia klikalności. Dodaj też tagi niezbędne do wczytywania plików dai.css i dai.js oraz do zaimportowania odtwarzacza wideo hls.js. Następnie zmodyfikuj plik dai.css, aby określić rozmiar i pozycję elementów strony. Na koniec w pliku dai.js określ zmienne, które przechowują informacje o żądaniu strumienia oraz funkcję initPlayer() uruchamianą po wczytaniu strony.

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

Wczytywanie pakietu IMA DAI SDK

Następnie dodaj platformę IMA za pomocą tagu skryptu w dai.html (przed tagiem 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>

Zainicjowanie StreamManagera i wysłanie żądania strumienia

Aby poprosić o zestaw reklam, utwórz element ima.dai.api.StreamManager, który odpowiada za żądania strumieni z DAI i zarządzanie nimi. Konstruktor pobiera element wideo, a wystąpienie wygenerowane przez niego pobiera element interfejsu reklamy do obsługi kliknięć reklam.

Następnie zdefiniuj funkcje, które wysyłają żądania strumieni. Ten przykład obejmuje funkcje związane zarówno z VOD, jak i transmisjami na żywo, które tworzą wystąpienia odpowiednio VODStreamRequest i LiveStreamRequest, a potem wywołują streamManager.requestStream() z parametrami streamRequest. W przypadku transmisji na żywo musisz też dodać moduł obsługi, który będzie nasłuchiwał zdarzeń metadanych czasowych i przekierowywał je do funkcji StreamManager. Możesz dodać komentarz lub usunąć znacznik komentarza z kodu, aby pasował do Twojego przypadku użycia. Obie metody wymagają opcjonalnego klucza interfejsu API. Jeśli korzystasz z chronionego strumienia, musisz utworzyć klucz uwierzytelniania DAI.

Żaden strumień w tym przykładzie nie jest chroniony, więc parametr apiKey nie jest używany.

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

Obsługa zdarzeń strumienia

Na koniec musisz wdrożyć detektory zdarzeń związanych z dużymi zdarzeniami wideo. Ten prosty przykład obsługuje zdarzenia LOADED, ERROR, AD_BREAK_STARTED i AD_BREAK_ENDED, wywołując funkcję onStreamEvent(). Ta funkcja obsługuje wczytywanie strumienia i błędy, a także wyłączanie elementów sterujących odtwarzacza podczas odtwarzania reklamy, co jest wymagane przez pakiet SDK. Podczas wczytywania strumienia odtwarzacz wideo wczytuje i odtwarza podany URL za pomocą funkcji loadUrl().

Możesz też skonfigurować detektory zdarzeń pause i start elementu wideo, by umożliwić użytkownikowi wznowienie odtwarzania, gdy reklama IMA zostanie wstrzymana podczas przerw na reklamę.

Aby umożliwić działanie DAI, Twój odtwarzacz niestandardowy musi przekazywać do pakietów IMA DAI SDK zdarzenia ID3 w przypadku transmisji na żywo, tak jak w przykładowym kodzie.

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

Znakomicie. Obecnie wysyłasz żądania i wyświetlanie reklam za pomocą pakietu IMA DAI SDK. Informacje o bardziej zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub przykładach w serwisie GitHub.