Ta strona została przetłumaczona przez Cloud Translation API.

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 IMA DAI SDK aplikacje wysyłają żądanie strumienia reklamy i treści wideo (VOD lub treści na żywo). SDK zwraca wtedy kod połączony strumień wideo, dzięki czemu nie trzeba przełączać się między reklamą a treścią wideo. w Twojej 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 biblioteki hls.js. Jeśli chcesz wyświetlić lub prześledzić przykładową integrację z obsługą HLS.js i odtwarzania w Safari, zapoznaj się z przykładem obsługi podkategorii HLS. Informacje o obsłudze 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 podów z dynamicznym wstawianiem reklam

Wdrożenie pod-serwera za pomocą pakietu IMA DAI SDK wymaga 2 głównych komponentów, które są omówione w tym przewodniku:

PodStreamRequest / PodVodStreamRequest: obiekt definiujący żądanie strumienia do Serwery reklamowe Google. Żądania określają kod sieci, a PodStreamRequest wymaga też klucza zasobu niestandardowego i opcjonalnie klucza 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ć:

Trzy 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

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.

Za pomocą wiersza poleceń, z katalogu zawierającego index.html uruchomienie pliku:
```
python -m http.server 8000
```
Uwaga: język http.server jest dostępny tylko w języku Python 3.x.
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.

Tworzenie prostego odtwarzacza 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, aby 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 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 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 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 Twojego konta Ad Managera 360.
CUSTOM_ASSET_KEY: używany tylko w przypadku transmisji na żywo. Niestandardowy klucz zasobu, który identyfikuje zdarzenie wyświetlania podgrupy w usłudze Ad Manager 360. Możesz go utworzyć za pomocą manipulatora pliku manifestu lub zewnętrznego partnera obsługującego pod.
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');
}

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

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

Wyświetlanie bloków reklamowych w transmisjach 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 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 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 poprosić o zestaw reklam, utwórz ima.dai.api.StreamManager, który odpowiada za żądania 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ę, która poprosi o podanie podzbioru obsługującego strumień VOD. 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ługuj zdarzenia strumienia

Blok reklamowy w transmisjach na żywo

Następnie zaimplementuj odbiorniki zdarzeń dla najważniejszych 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. 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.

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

Na tym etapie wdrażasz detektory zdarzeń dla metadanych, aby powiadamiać pakiet SDK o wystąpieniu zdarzeń Ad. 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. 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, 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 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 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 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 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ń odtwarzacza

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. Teraz wysyłasz żądania reklam i wyświetlasz je w strumieniu z wyświetlaniem bloków reklamowych za pomocą pakietu IMA DAI SDK dla HTML5. Więcej informacji o zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub w przykładach na GitHubie.