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

Blok reklamowy z dynamicznym wstawianiem reklam

W tym przewodniku pokazujemy, jak odtwarzać strumień wyświetlania bloków reklamowych z dynamicznym wstawianiem reklam w przypadku treści na żywo lub VOD przy użyciu pakietu IMA DAI SDK dla HTML5 z odtwarzaczem, który do odtwarzania obsługuje plik hls.js. Jeśli chcesz zobaczyć lub śledzić ukończoną integrację przykładową obsługującą zarówno odtwarzanie HLS.js, jak i w Safari, zapoznaj się z przykładem wyświetlania poda HLS. Informacje o obsłudze DASH.js znajdziesz w przykładzie wyświetlania bloku DASH. Możesz je pobrać ze strony wersji HTML5 DAI w GitHub.

Omówienie wyświetlania bloków reklamowych z dynamicznym wstawianiem reklam

Implementacja bloków reklamowych z użyciem pakietu IMA DAI SDK obejmuje 2 główne komponenty, które opisujemy w tym przewodniku:

• PodStreamRequest / PodVodStreamRequest: obiekt, który określa żądanie strumienia wysyłane do serwerów reklamowych Google. Żądania zawierają kod sieci. PodStreamRequest wymaga też niestandardowego klucza zasobu i opcjonalnego klucza interfejsu API. Zawierają też inne parametry opcjonalne.

• StreamManager: obiekt obsługujący komunikację między strumieniem wideo a pakietem IMA DAI SDK, np. uruchamianie pingów śledzenia i przekazywania zdarzeń strumienia do wydawcy.

Wymagania wstępne

Zanim zaczniesz, będziesz mieć:

• Trzy puste pliki:

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

• Python zainstalowany na komputerze, serwer WWW lub inne hostowane środowisko programistyczne do użycia

Konfigurowanie środowiska programistycznego

Pakiet SDK wczytuje zależności przy użyciu tego samego protokołu co strona, z której jest wczytywana. 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ń w katalogu zawierającym uruchomienie pliku index.html:

   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, na przykład serwera HTTP Apache.

Utwórz prosty odtwarzacz wideo

Najpierw zmodyfikuj plik dai.html, by utworzyć prosty element wideo HTML5, oraz div na potrzeby elementów interfejsu reklamy. 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 będą przechowywać informacje o żądaniu strumienia, oraz funkcję initPlayer() uruchamianą po wczytaniu strony.

Stałe żądania strumienia są następujące:

• BACKUP_STREAM: URL strumienia zapasowego, który ma być odtwarzany w przypadku wystąpienia błędu krytycznego w procesie wyświetlania reklam.

• STREAM_URL: używany tylko w przypadku transmisji na żywo. Adres URL strumienia wideo podany przez manipulator pliku manifestu lub partnera zewnętrznego, który korzysta z podów. Powinno ono wymagać, by przed wysłaniem żądania wstawić identyfikator strumienia z pakietu IMA DAI SDK. W tym przypadku URL strumienia zawiera obiekt zastępczy [[STREAMID]], który przed wysłaniem żądania jest zastępowany identyfikatorem strumienia.

• NETWORK_CODE: kod sieci powiązany z kontem Ad Managera 360.

• CUSTOM_ASSET_KEY: używany tylko w przypadku transmisji na żywo. Niestandardowy klucz zasobu, który identyfikuje zdarzenie wyświetlania bloku reklamowego w usłudze Ad Manager 360. Może go utworzyć manipulator pliku manifestu lub zewnętrzny partner obsługujący pody.

• API_KEY: używany tylko w przypadku transmisji na żywo. Opcjonalny klucz interfejsu API, który może służyć do pobierania 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');
}

Wczytywanie pakietu IMA DAI SDK

Następnie dodaj platformę DAI 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>
...

Inicjowanie narzędzia StreamManager i wysyłanie żądań transmisji na żywo lub VOD

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

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

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

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

W tym kroku implementujesz detektory zdarzeń dla metadanych, które będą powiadamiać pakiet SDK o zdarzeniach reklamowych. Wykrywanie zdarzeń z metadanymi typu In-Stream 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 używanego backendu z DAI. Więcej informacji znajdziesz w naszym przewodniku dotyczącym metadanych czasowych.

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

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

Aby automatycznie odtworzyć film, gdy wszystko zostanie załadowane i gotowe, aktywuj zdarzenie MANIFEST_PARSED HLS.js.

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

Jeśli używasz odtwarzacza DASH.js, musisz używać różnych ciągów znaków w celu nasłuchiwania metadanych ID3 w przypadku transmisji 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 odtwarzaniem filmu, gdy wszystko zostanie wczytane i gotowe, włącz nasłuchiwanie zdarzenia MANIFEST_LOADED DASH.js.

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 transmisji na żywo używasz odtwarzacza Shaka, do nasłuchiwania zdarzeń metadanych użyj ciągu 'emsg'. Następnie użyj tych danych w wywołaniu zdarzenia 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 ze strumieniami VOD (format strumieni DASH)

Jeśli do odtwarzania strumienia VOD używasz odtwarzacza Shaka, dodaj ciąg znaków 'timelineregionenter', by nasłuchiwać zdarzeń metadanych. Następnie użyj danych komunikatu o zdarzeniu w wywołaniu StreamManager.processMetadata() z ciągiem tekstowym '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 do zdarzeń pause i start elementu wideo, aby umożliwić użytkownikowi wznowienie odtwarzania, gdy pakiet SDK zostanie wstrzymany podczas przerw na reklamę.

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

Znakomicie. Żądasz i wyświetlasz reklamy w bloku reklamowym z pakietem IMA DAI SDK dla HTML5. Więcej informacji o bardziej zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach i przykładach na GitHubie.