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 dynamicznego wstawiania reklam

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

Omówienie dynamicznego wstawiania reklam w IMA

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 dotyczące transmisji na żywo podają klucz zasobu, a żądania dotyczące VOD podają identyfikator CMS i identyfikator filmu. Oba typy żądań mogą opcjonalnie zawierać klucz API potrzebny do uzyskania dostępu do określonych strumieni oraz kod sieci Google Ad Managera dla pakietu IMA SDK, który obsługuje identyfikatory reklam zgodnie z ustawieniami Google Ad Managera.
  • StreamManager: obiekt obsługujący 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, którego używa strona, z której jest wczytywany. Aby przetestować aplikację, musisz użyć serwera internetowego. 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 http://localhost:8000/

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

Tworzenie prostego odtwarzacza filmów

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";

// Ad Manager network code.
var NETWORK_CODE = 'NETWORK_CODE';

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 danych 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 zawiera 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ć element obsługi, który będzie nasłuchiwać zdarzeń metadanych z opóźnieniem i przekazywać je do elementu StreamManager. Możesz dodać lub usunąć komentarze do kodu, aby dostosować go do swoich potrzeb. Obie metody przyjmują opcjonalny klucz API. Jeśli korzystasz ze strumienia chronionego, 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, NETWORK_CODE);
  // 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, NETWORK_CODE);
}

function requestVODStream(cmsId, videoId, apiKey, networkCode) {
  var streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.apiKey = apiKey;
  streamRequest.networkCode = networkCode;
  streamManager.requestStream(streamRequest);
}

function requestLiveStream(assetKey, apiKey, networkCode) {
  var streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.apiKey = apiKey;
  streamRequest.networkCode = networkCode;
  streamManager.requestStream(streamRequest);
}

Obsługa zdarzeń strumienia

Na koniec musisz zaimplementować odbiorniki zdarzeń dla najważniejszych zdarzeń wideo. Ten prosty przykład obsługuje zdarzenia LOADED, ERROR, AD_BREAK_STARTED i AD_BREAK_ENDED przez wywołanie funkcji 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 przez 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.