Konfigurowanie pakietu IMA SDK na potrzeby DAI

Wybierz platformę: HTML5 Android iOS tvOS Cast Roku

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. Za pomocą pakietów IMA DAI SDK aplikacje wysyłają żądanie strumienia reklamy i treści wideo – VOD lub treści na żywo. Pakiet SDK zwraca wtedy połączony strumień wideo, dzięki czemu nie musisz zarządzać przełączaniem między reklamą a treścią wideo w aplikacji.

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

Dynamiczne wstawianie reklam z pełną obsługą

Ten przewodnik pokazuje, jak zintegrować pakiet IMA DAI SDK z aplikacją odtwarzacza wideo. Jeśli chcesz zobaczyć gotową przykładową integrację lub postępować zgodnie z nią, pobierz prosty przykład z GitHub.

Omówienie IMA DAI

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

  • StreamRequest– VODStreamRequest lub LiveStreamRequest: obiekt, który definiuje żądanie strumienia. Żądania strumieni mogą dotyczyć transmisji wideo na żądanie lub transmisji na żywo. Żądania transmisji na żywo zawierają klucz zasobu, a żądania VOD – identyfikator CMS i identyfikator wideo. Oba typy żądań mogą opcjonalnie zawierać klucz API potrzebny do uzyskania dostępu do określonych strumieni oraz kod sieci Google Ad Managera, aby pakiet IMA SDK mógł obsługiwać identyfikatory reklam zgodnie z ustawieniami Google Ad Managera.
  • StreamManager: Obiekt, który obsługuje strumienie dynamicznego wstawiania reklam i interakcje z backendem DAI. Menedżer strumienia obsługuje też pingi śledzące i przesyła zdarzenia strumienia i reklam do wydawcy.

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 jest wczytywany, więc do testowania aplikacji musisz używać serwera WWW. Szybkim sposobem na uruchomienie lokalnego serwera deweloperskiego jest użycie wbudowanego serwera Pythona.

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

    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 odtwarzacza wideo

Najpierw zmodyfikuj plik dai.html, aby utworzyć element wideo HTML5 i element div, który będzie używany do kliknięcia. Poniższy przykład importuje pakiet IMA DAI SDK. Więcej informacji znajdziesz w artykule Importowanie pakietu IMA DAI SDK.

Dodaj też niezbędne tagi, aby wczytać pliki dai.css i dai.js oraz zaimportować odtwarzacz wideo hls.js. Następnie zmień dai.css, aby określić rozmiar i położenie elementów strony. Na koniec w dai.js zdefiniuj zmienne do przechowywania informacji o żądaniu strumienia, funkcję initPlayer(), która ma być uruchamiana po wczytaniu strony, i skonfiguruj przycisk odtwarzania, aby po kliknięciu wysyłał żądanie strumienia.

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>


#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}

Aby wznowić odtwarzanie podczas wstrzymanych przerw na reklamy, skonfiguruj odbiorniki zdarzeń dla zdarzeń pause i start elementu wideo, aby wyświetlać i ukrywać elementy sterujące odtwarzaczem.

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}

Wczytaj pakiet IMA DAI SDK

Następnie dodaj platformę IMA za pomocą tagu skryptu w pliku dai.html przed tagiem dai.js.

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>

Zainicjuj StreamManager

Aby poprosić o zestaw reklam, utwórz ima.dai.api.StreamManager, który odpowiada za wysyłanie żądań strumieni DAI i zarządzanie nimi. Konstruktor przyjmuje element wideo i element interfejsu reklamy do obsługi kliknięć reklam.

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}

Przesyłanie prośby o strumień

Zdefiniuj funkcje do wysyłania żądań strumieni. Ten przykład zawiera funkcje zarówno dla filmów VOD, jak i transmisji na żywo, które tworzą instancje klasy VODStreamRequest i klasy LiveStreamRequest. Gdy masz instancję streamRequest, wywołaj metodę streamManager.requestStream() z instancją żądania strumienia.

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

Obie metody żądania strumienia przyjmują opcjonalny klucz interfejsu API. Jeśli używasz chronionego strumienia, musisz utworzyć klucz uwierzytelniania DAI. Więcej informacji znajdziesz w artykule Uwierzytelnianie żądań strumienia wideo na żywo za pomocą kluczy uwierzytelniania DAI. Żaden strumień w tym przykładzie nie jest chroniony za pomocą klucza uwierzytelniania DAI, więc apiKey nie jest używany.

Analizowanie metadanych strumienia

Musisz też dodać moduł obsługi, który będzie nasłuchiwać zdarzeń metadanych z określonym czasem i przekazywać je do klasy StreamManager, aby IMA mogła emitować zdarzenia reklam podczas przerw na reklamy:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we 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);
      });
    }
  });
}

W tym przewodniku do odtwarzania strumienia używany jest odtwarzacz hls.js, ale implementacja metadanych zależy od typu używanego odtwarzacza.

Obsługa zdarzeń strumienia

Wdrażaj detektory zdarzeń dla najważniejszych zdarzeń wideo. W tym przykładzie zdarzenia LOADED, ERROR, AD_BREAK_STARTED i AD_BREAK_ENDED są obsługiwane przez wywołanie funkcji onStreamEvent(). Ta funkcja obsługuje wczytywanie strumienia, błędy strumienia i wyłączanie elementów sterujących odtwarzacza podczas odtwarzania reklam, co jest wymagane przez pakiet IMA SDK.

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
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');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
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();
  });
}

Po załadowaniu strumienia odtwarzacz wideo wczytuje i odtwarza podany adres URL za pomocą funkcji loadUrl().

To wszystko. Teraz wysyłasz żądania reklam i wyświetlasz je za pomocą pakietu IMA DAI SDK. Aby dowiedzieć się więcej o bardziej zaawansowanych funkcjach pakietu SDK, zapoznaj się z innymi przewodnikami lub przykładami na GitHubie.