Pierwsze kroki z pakietem IMA DAI SDK

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą żądania reklam z Serwer reklam zgodny i zarządzanie odtwarzaniem reklam w aplikacjach. Dzięki pakietom SDK IMA DAI aplikacje żądania strumieniowego przesyłania danych reklamy i treści wideo – VOD lub treści na żywo. SDK zwraca wtedy typ połączony strumień wideo, dzięki czemu nie trzeba przełączać się między reklamą a treścią wideo. w Twojej aplikacji.

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

Blok reklamowy z dynamicznym wstawianiem reklam

Ten przewodnik pokazuje, jak odtworzyć strumień wyświetlania bloków reklamowych z dynamicznym wstawianiem reklam w przypadku transmisji na żywo lub VOD. za pomocą pakietu IMA DAI SDK na potrzeby HTML5 i odtwarzacza wideo, który korzysta z tagu hls.js do odtwarzania. Jeśli chcesz zobaczyć gotowy fragment lub zapoznać się z nim z obsługą zarówno HLS.js, jak i Safari, zapoznaj się z Przykład wyświetlania poda HLS. Informacje o obsłudze DASH.js znajdziesz w przykładzie wyświetlania bloków reklamowych DASH. Możesz pobrać te przykładowe aplikacje z wersji GitHub HTML5 z funkcją DAI .

Omówienie wyświetlania podów z dynamicznym wstawianiem reklam

Implementacja wyświetlania bloków reklamowych za pomocą pakietu IMA DAI SDK obejmuje 2 główne komponenty: w tym przewodniku:

  • PodStreamRequest / PodVodStreamRequest: obiekt definiujący żądanie strumienia do Serwery reklamowe Google. W żądaniach jest określony kod sieci, a parametry PodStreamRequest wymaga też niestandardowego klucza zasobu i opcjonalnego klucza Klucz interfejsu API. Oba typy zawierają inne opcjonalne parametry.

  • StreamManager: obiekt obsługujący komunikację między strumienia wideo i pakietu IMA DAI SDK, np. uruchamiania pingów śledzących czy i przekazywać wydawcy zdarzenia strumienia.

Wymagania wstępne

Zanim zaczniesz, musisz mieć:

  • Trzy puste pliki:

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

  • Na Twoim komputerze zainstalowany jest język Python, serwer WWW lub inny hostowany program rozwojowy środowisko używane do testowania

Konfigurowanie środowiska programistycznego

Pakiet SDK wczytuje zależności za pomocą tego samego protokołu co strona z musisz użyć serwera WWW, aby ją przetestować. Krótka aby uruchomić lokalny serwer programistyczny, użyj wbudowanego serwera Pythona.

  1. Za pomocą wiersza poleceń, z katalogu zawierającego index.html uruchomienie pliku:

    python -m http.server 8000

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

    Możesz również użyć dowolnego innego hostowanego środowiska programistycznego lub serwera WWW, takiego jak jako serwer Apache HTTP.

Utwórz prosty odtwarzacz wideo

Najpierw zmodyfikuj plik dai.html, by utworzyć prosty element wideo HTML5 i element div do elementów interfejsu reklamy. Dodaj też tagi niezbędne do wczytywania pliku dai.css i dai.js oraz zaimportować odtwarzacz wideo hls.js.

Następnie zmodyfikuj plik dai.css, by określić rozmiar i pozycję elementów strony. Na koniec w tagu dai.js zdefiniuj zmienne do przechowywania informacji o żądaniach strumienia. i funkcja initPlayer() do uruchamiania po wczytaniu strony.

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

  • BACKUP_STREAM: adres URL strumienia zapasowego, który będzie odtwarzany na wypadek procesu wyświetlania reklam. napotka błąd krytyczny.

  • STREAM_URL: używany tylko w przypadku transmisji na żywo. Adres URL strumienia wideo dostarczony przez za pomocą manipulatora manifestu lub partnera zewnętrznego, który obsługuje bloki reklamowe. Powinna musisz wstawić identyfikator strumienia dostarczony przez pakiet IMA DAI SDK przed przesłać prośbę. W tym przypadku URL transmisji zawiera zmienną, [[STREAMID]], który jest zastępowany identyfikatorem strumienia przed wysłaniem żądania.

  • NETWORK_CODE: kod sieci Twojego konta Ad Managera 360.

  • CUSTOM_ASSET_KEY: używany tylko w przypadku transmisji na żywo. Niestandardowy klucz pliku, który identyfikuje zdarzenie wyświetlenia bloku reklamowego w usłudze Ad Manager 360. Kto może ją utworzyć za pomocą manipulatora pliku manifestu lub zewnętrznego partnera obsługującego pody.

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

Wczytaj pakiet IMA DAI SDK

Następnie dodaj platformę DAI, używając tagu skryptu w pliku dai.html przed tagiem. dla 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>
...

Zainicjuj usługę StreamManager i wyślij żądanie strumienia na żywo lub VOD

Blok reklamowy w transmisjach na żywo

Aby poprosić o zestaw reklam, utwórz ima.dai.api.StreamManager, który odpowiada za żądania strumieni DAI i zarządzanie nimi. Konstruktor pobiera element wideo, a wystąpienie przechwytuje reklamę z elementu interfejsu reklamy. interakcje.

Następnie zdefiniuj funkcję, która wysyła żądanie bloku reklamowego do transmisji na żywo. Ta funkcja najpierw tworzy PodStreamRequest, konfiguruje je za pomocą żądania streamRequest podane w kroku 2, a następnie wywołuje funkcję streamManager.requestStream() z danym 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 poprosić o zestaw reklam, utwórz ima.dai.api.StreamManager, który odpowiada za żądania strumieni DAI i zarządzanie nimi. Konstruktor pobiera element wideo, a wystąpienie przechwytuje reklamę z elementu interfejsu reklamy. interakcje.

Następnie zdefiniuj funkcję, która wysyła żądanie poda obsługującego strumień VOD. Ta funkcja najpierw tworzy PodVodStreamRequest, konfiguruje je za pomocą żądania streamRequest podane w kroku 2, a następnie wywołuje funkcję streamManager.requestStream() z danym 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ługuj zdarzenia strumienia

Blok reklamowy w transmisjach na żywo

Następnie zaimplementuj detektory ważnych zdarzeń wideo. W tym przykładzie STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED i AD_BREAK_ENDED zdarzeń, wywołując funkcję onStreamEvent(). Ta funkcja obsługuje strumień ładowania i błędów, a także wyłączenie elementów sterujących odtwarzaczem, gdy reklama jest wyświetlana odtwarzania, co jest wymagane przez pakiet SDK. Po wczytaniu strumienia film odtwarzacz wczytuje i odtwarza podany URL 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 detektory ważnych zdarzeń wideo. W tym przykładzie STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED i AD_BREAK_ENDED poprzez wywołanie funkcji onStreamEvent(). Ten obsługuje wczytywanie strumienia i błędy, a także wyłącza odtwarzacz elementów sterujących podczas odtwarzania reklamy. Jest to wymagane przez pakiet SDK.

Oprócz tego strumienie wyświetlania bloków reklamowych VOD wymagają wywołania StreamManager.loadStreamMetadata() w odpowiedzi na STREAM_INITIALIZED. Poproś też o adres URL transmisji na swojej stronie, partnera w zakresie technologii wideo (VTP). Po pomyślnym wywołaniu loadStreamMetadata() wywołuje zdarzenie LOADED, które należy wywołać funkcję loadStream() za pomocą adresu URL transmisji, aby wczytać i odtworzyć transmisję.

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 wdrożysz detektory zdarzeń dla metadanych, aby powiadamiały pakiet SDK, gdy zdarzeń reklamowych. Nasłuchiwanie zdarzeń metadanych In-Stream może się różnić w zależności od format strumienia (HLS lub DASH), typ (transmisja na żywo lub VOD), typu odtwarzacza i używanego backendu DAI. Zobacz nasze Metadane .

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

Jeśli korzystasz z odtwarzacza HLS.js, posłuchaj w zdarzeniu FRAG_PARSING_METADATA HLS.js, by pobrać metadane ID3 i przekazać je do Pakiet SDK z StreamManager.processMetadata().

Aby automatycznie odtworzyć film, gdy wszystko będzie wczytane i gotowe, posłuchaj: zdarzenie MANIFEST_PARSED HLS.js, które aktywuje 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 oraz typ strumienia Na żywo i VOD)

Jeśli korzystasz z odtwarzacza DASH.js, musisz użyć różnych ciągów znaków, aby nasłuchiwać metadanych ID3 w przypadku transmisji na żywo lub VOD. strumienie:

  • 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 po załadowaniu wszystkich elementów: nasłuchuje 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);
}

Shaka Player z transmisjami na żywo (format DASH)

Jeśli używasz odtwarzacza Shaki do odtwarzania na żywo, użyj ciągu 'emsg', aby nasłuchiwać zdarzeń metadanych. Następnie użyj danych komunikatu o zdarzeniu w wywołaniu pod numerem 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 używasz odtwarzacza Shaki do Odtwarzanie strumienia VOD, aby nasłuchiwać, użyj ciągu 'timelineregionenter' zdarzenia związane z metadanymi. Następnie użyj danych komunikatu o zdarzeniu w rozmowie, StreamManager.processMetadata() z ciągiem '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ń graczy

Dodaj detektory zdarzeń do zdarzeń pause i start elementu wideo, aby zezwolić wznowienie odtwarzania w przypadku wstrzymania działania pakietu SDK w czasie 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. Zamawiasz i wyświetlasz reklamy w strumieniu bloku reklamowego z pakiet IMA DAI SDK dla HTML5. Aby dowiedzieć się więcej o bardziej zaawansowanych funkcjach pakietu SDK, zobacz innych przewodników lub przykładów GitHub.