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

Wyświetlanie bloków reklamowych w ramach dynamicznego wstawiania reklam

Ten przewodnik pokazuje, jak odtwarzać strumień z dynamicznego wstawiania reklam w ramach treści na żywo lub VOD za pomocą pakietu IMA DAI SDK dla HTML5 z odtwarzaczem, który korzysta z elementu hls.js. Aby wyświetlić lub przejrzeć przykładową, ukończoną integrację z obsługą zarówno HLS.js, jak i odtwarzania w Safari, zapoznaj się z przykładem obsługi bloku reklamowego HLS. Informacje o obsługiwaniu DASH.js znajdziesz w przykładzie wyświetlania bloków reklamowych DASH. Te przykładowe aplikacje możesz pobrać na stronie GitHub z wersją HTML5 DAI.

Omówienie wyświetlania bloków reklamowych w ramach dynamicznego wstawiania reklam

Wdrożenie wyświetlania bloków reklamowych za pomocą pakietu IMA DAI SDK wymaga 2 głównych komponentów, które są opisane w tym przewodniku:

  • PodStreamRequest / PodVodStreamRequest: obiekt definiujący żądanie strumienia do serwerów reklamowych Google. Żądania określają kod sieci, a PodStreamRequest wymaga też klucza zasobu niestandardowego i opcjonalnie klucza interfejsu API. Oba zawierają inne parametry opcjonalne.

  • StreamManager: obiekt obsługujący komunikację między strumieniem wideo a pakietem IMA DAI SDK, np. wysyła pingi śledzące i przekazuje zdarzenia strumienia do wydawcy.

Wymagania wstępne

Zanim zaczniesz, musisz mieć:

  • 3 puste pliki:

    • dai.html
    • dai.css
    • dai.js

  • Python zainstalowany na komputerze lub serwer WWW albo inne hostowane środowisko programistyczne do testowania.

Konfigurowanie środowiska programistycznego

Ponieważ pakiet SDK wczytuje zależności za pomocą tego samego protokołu co strona, z której jest wczytywany, do testowania aplikacji musisz użyć serwera WWW. Szybki sposób na uruchomienie lokalnego serwera programistycznego to 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 hostowanego środowiska programistycznego lub serwera WWW, np. serwera HTTP Apache.

Tworzenie odtwarzacza wideo

Najpierw zmodyfikuj plik dai.html, aby utworzyć element wideo HTML5 i element div do użycia w elementach interfejsu użytkownika reklamy. Dodaj też tagi niezbędne do wczytania 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 zdefiniuj zmienne, które będą przechowywać informacje o żądaniu strumienia, oraz funkcję initPlayer(), która ma być wykonywana podczas wczytywania strony.

Stały parametry żądania strumienia:

  • BACKUP_STREAM: adres URL strumienia zapasowego do odtworzenia na wypadek, gdyby proces reklam napotkał nieodwracalny błąd.

  • STREAM_URL: używane tylko w przypadku transmisji na żywo. Adres URL strumienia wideo podany przez usługę manipulacji plikiem manifestu lub przez zewnętrznego partnera korzystającego z funkcji wyświetlania bloków reklamowych. Zanim prześlesz żądanie, musisz w nim podać identyfikator strumienia dostarczony przez pakiet IMA DAI SDK. W takim przypadku adres URL strumienia zawiera obiekt zastępczy [[STREAMID]], który przed wysłaniem żądania jest zastępowany identyfikatorem strumienia.

  • NETWORK_CODE: kod sieci konta Ad Managera 360.

  • CUSTOM_ASSET_KEY: używane tylko w przypadku transmisji na żywo. Niestandardowy klucz zasobu, który identyfikuje zdarzenie wyświetlania w Pod w usłudze Ad Manager 360. Możesz go utworzyć za pomocą manipulatora pliku manifestu lub zewnętrznego partnera obsługującego wyświetlanie bloków reklamowych.

  • API_KEY: używane tylko w przypadku transmisji na żywo. Opcjonalny klucz interfejsu API, który może być wymagany do pobrania identyfikatora strumienia z pakietu 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');
}

Załaduj pakiet IMA DAI SDK

Następnie dodaj platformę DAI 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 dotyczącego transmisji na żywo lub VOD

Obsługa poddomeny transmisji na żywo

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ć interakcje z reklamą.

Następnie zdefiniuj funkcję do żądania transmisji na żywo z Pod Serving. Ta funkcja najpierw tworzy obiekt PodStreamRequest, konfiguruje go za pomocą parametrów streamRequest podanych w kroku 2, a następnie wywołuje funkcję streamManager.requestStream() z tym obiektem żądania.

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

Wyświetlanie bloków reklamowych VOD

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ć interakcje z reklamą.

Następnie zdefiniuj funkcję do wysyłania żądania strumienia VOD z bloku reklamowego. Ta funkcja najpierw tworzy obiekt PodVodStreamRequest, konfiguruje go za pomocą parametrów streamRequest podanych w kroku 2, a następnie wywołuje funkcję streamManager.requestStream() z tym obiektem żądania.

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

Obsługa zdarzeń strumienia

Obsługa poddomeny transmisji na żywo

Następnie zaimplementuj odbiorniki zdarzeń dla najważniejszych zdarzeń wideo. W tym przykładzie zdarzenia STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED i AD_BREAK_ENDED są obsługiwane 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. Po załadowaniu strumienia odtwarzacz wczytuje podany adres URL i odtwarza go za pomocą funkcji 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);
}

Wyświetlanie bloków reklamowych VOD

Następnie zaimplementuj odbiorniki zdarzeń dla najważniejszych zdarzeń wideo. Ten przykład obsługuje zdarzenia STREAM_INITIALIZED, 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 wyświetlania reklamy, co jest wymagane przez pakiet SDK.

Dodatkowo strumienie VOD Pod Serving wymagają wywołania funkcji StreamManager.loadStreamMetadata() w odpowiedzi na zdarzenie STREAM_INITIALIZED. Musisz też poprosić o adres URL strumienia od partnera technologicznego ds. wideo (VTP). Po pomyślnym wywołaniu funkcji loadStreamMetadata() uruchamia ona zdarzenie LOADED, w ramach którego należy wywołać funkcję loadStream() z adresem URL strumienia, aby wczytać i odtwarzać strumień.

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

Obsługa metadanych strumienia

Na tym etapie wdrażasz detektory zdarzeń dla metadanych, aby powiadamiać pakiet SDK o wystąpieniu zdarzeń. Odsłuchiwanie zdarzeń metadanych w strumieniu może się różnić w zależności od formatu strumienia (HLS lub DASH), typu strumienia (transmisja na żywo lub VOD), typu odtwarzacza i typu używanego backendu DAI. Więcej informacji znajdziesz w przewodniku dotyczącym metadanych.

Format strumienia HLS (transmisje na żywo i VOD, odtwarzacz HLS.js)

Jeśli używasz odtwarzacza HLS.js, nasłuchuj zdarzenie HLS.js FRAG_PARSING_METADATA, aby pobrać metadane ID3 i przekazać je do pakietu SDK za pomocą StreamManager.processMetadata().

Aby automatycznie odtworzyć film po załadowaniu i przygotowaniu wszystkich elementów, przechwyć zdarzenie HLS.js MANIFEST_PARSED, aby wywołać odtwarzanie.

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 (format strumieni DASH, typ strumienia na żywo i VOD)

Jeśli używasz odtwarzacza DASH.js, musisz użyć różnych ciągów znaków, aby odsłuchać metadane ID3 w przypadku strumieni na żywo lub VOD:

  • Transmisje na żywo: 'https://developer.apple.com/streaming/emsg-id3'
  • Strumienie VOD: 'urn:google:dai:2018'

Przekaż metadane ID3 do pakietu SDK za pomocą StreamManager.processMetadata().

Aby automatycznie wyświetlać elementy sterujące filmem po załadowaniu i gotowości wszystkich elementów, nasłuchuj zdarzenia DASH.js MANIFEST_LOADED.

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

Odtwarzacz Shaka z transmisjami na żywo (format strumieni DASH)

Jeśli do odtwarzania strumieniowego używasz odtwarzacza Shaka, użyj ciągu 'emsg', aby nasłuchiwać zdarzeń metadanych. Następnie użyj danych z wiadomości o zdarzeniu w wywołaniu do 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});
}

Odtwarzacz Shaka z strumieniami VOD (w formacie strumieni DASH)

Jeśli do odtwarzania strumienia VOD używasz odtwarzacza Shaka, użyj ciągu 'timelineregionenter', aby nasłuchiwać zdarzeń metadanych. Następnie użyj danych wiadomości zdarzenia w wywołaniu do funkcji StreamManager.processMetadata() z ciągiem znaków '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);
       }
}

Obsługa zdarzeń odtwarzacza

Dodaj detektory zdarzeń do zdarzeń pause i start elementu wideo, aby umożliwić użytkownikowi wznowienie odtwarzania po wstrzymaniu przez pakiet SDK podczas przerw na reklamy.

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

Czyszczenie komponentów IMA DAI

Po zakończeniu przesyłania żądań i wyświetlania reklam w strumieniu z dynamicznym wstawianiem reklam za pomocą pakietu IMA DAI SDK zalecamy usunięcie wszystkich zasobów po zakończeniu sesji Pod Serving. Wywołanie StreamManager.destroy() zatrzymuje odtwarzanie strumienia, zatrzymuje śledzenie reklam i zwalnia wszystkie załadowane zasoby strumienia.

Więcej informacji o zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub w przykładach na GitHubie.