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 aplikacjach. Dzięki pakietom IMA DAI SDK aplikacje wysyłają żądanie strumienia reklamy i treści wideo (VOD lub treści na żywo). Pakiet SDK zwraca następnie połączony strumień wideo, dzięki czemu nie musisz zarządzać przełączaniem się między reklamą a filmem z treściami w aplikacji.

Wybierz interesujące Cię rozwiązanie DAI

Pełna obsługa DAI

Ten przewodnik pokazuje, jak zintegrować pakiet IMA DAI SDK z prostym odtwarzaczem wideo. Jeśli chcesz zobaczyć lub prześledzić przykładową integrację, pobierz prosty przykład z GitHuba.

Omówienie IMA DAI

Wdrażanie pakietu IMA DAI SDK obejmuje 2 główne komponenty, jak pokazano w tym przewodniku:

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

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 za pomocą tego samego protokołu co strona, z której jest wczytywany, dlatego do testowania aplikacji musisz użyć serwera WWW. Szybkim sposobem na uruchomienie lokalnego serwera deweloperskiego jest użycie wbudowanego serwera Pythona.

  1. W katalogu zawierającym plik index.html uruchom w wierszu poleceń:

    python -m http.server 8000

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

    Możesz też użyć dowolnego innego serwera WWW, np. serwera HTTP Apache.

Tworzenie prostego odtwarzacza wideo

Najpierw zmodyfikuj plik dai.html, aby utworzyć prosty element wideo HTML5 i element div do użycia w przypadku kliknięcia. Dodaj też tagi niezbędne do wczytania plików dai.css i dai.js oraz do zaimportowania odtwarzacza wideo hls.js. Następnie zmień plik dai.css, aby określić rozmiar i pozycję elementów strony. Na koniec w pliku dai.js zdefiniuj zmienne, które będą przechowywać informacje o żądaniu strumienia, oraz funkcję initPlayer(), która ma być wykonywana podczas wczytywania 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');
}

Załaduj pakiet IMA DAI SDK

Następnie dodaj platformę IMA za pomocą tagu skryptu w pliku 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>

Inicjalizacja StreamManagera i wysłanie żądania strumienia

Aby żądać zestawu reklam, utwórz obiekt ima.dai.api.StreamManager, który odpowiada za żądanie strumieni DAI i zarządzanie nimi. Konstruktor przyjmuje element wideo, a wynikowa instancja przyjmuje element interfejsu reklamy, aby obsługiwać kliknięcia reklam.

Następnie zdefiniuj funkcje, które wysyłają żądania strumieni. Ten przykład obejmuje funkcje zarówno dla VOD, jak i transmisji na żywo, które tworzą instancje odpowiednio VODStreamRequest i LiveStreamRequest, a następnie wywołują funkcję streamManager.requestStream() z parametrami streamRequest. W przypadku transmisji na żywo musisz też dodać taki przetwarzacz, który będzie nasłuchiwać zdarzeń metadanych zsynchronizowanych z czasem i przekazywać je do funkcji StreamManager. Możesz dodawać i usuwać komentarze do kodu, aby dostosować go do swoich potrzeb. Obie metody przyjmują opcjonalny klucz API. Jeśli używasz chronionego strumienia, musisz utworzyć klucz uwierzytelniania DAI.

Żaden strumień w tym przykładzie nie jest chroniony, więc 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 zaimplementować odbiorniki zdarzeń dla najważniejszych zdarzeń związanych z filmem. 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łącza elementy sterujące odtwarzaczem podczas odtwarzania reklamy, co jest wymagane przez pakiet SDK. Gdy strumień zostanie załadowany, odtwarzacz wideo wczyta podany adres URL i odtworzy go za pomocą funkcji loadUrl().

Możesz też skonfigurować odbiorniki zdarzeń dla zdarzeń pause i start elementu wideo, aby umożliwić użytkownikowi wznowienie odtwarzania po wstrzymaniu IMA podczas przerw na reklamy.

Aby współpracować z DAI, Twój niestandardowy odtwarzacz musi przekazywać zdarzenia ID3 dotyczące transmisji na żywo do pakietów IMA DAI SDK, jak pokazano 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. Reklamy są teraz żądane i wyświetlane za pomocą pakietu IMA DAI SDK. Więcej informacji o zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub przykładach na GitHubie.