Configura con DAI servizio completo

Seleziona la piattaforma: HTML5 Android iOS tvOS Cast Roku

Questa guida illustra come integrare l'SDK IMA DAI in un'app video player. Se vuoi visualizzare o seguire un'integrazione di esempio completata, scarica l'esempio semplice da GitHub.

Panoramica di IMA DAI

L'implementazione dell'SDK IMA DAI prevede due componenti principali, come mostrato in questa guida:

  • StreamRequest: un VODStreamRequest o un LiveStreamRequest. Un oggetto che definisce una richiesta di stream. Le richieste di stream possono riguardare video on demand o live streaming. Le richieste di live streaming specificano una chiave asset, mentre le richieste VOD specificano un ID CMS e un ID video. Entrambi i tipi di richiesta possono includere facoltativamente una chiave API necessaria per accedere agli stream specificati e un codice di rete Google Ad Manager per consentire all'SDK IMA di gestire gli identificatori degli annunci come specificato nelle impostazioni di Google Ad Manager.
  • StreamManager: un oggetto che gestisce gli stream di inserimento di annunci dinamici e le interazioni con il backend DAI. Il gestore degli stream gestisce anche i ping di monitoraggio e inoltra gli eventi di stream e annunci al publisher.

Prerequisiti

  • Tre file vuoti
    • dai.html
    • dai.css
    • dai.js
  • Python installato sul computer o un server web da utilizzare per i test

Avvia un server di sviluppo

Poiché l'SDK IMA DAI carica le dipendenze utilizzando lo stesso protocollo della pagina da cui viene caricato, devi utilizzare un server web per testare la tua app. Un modo rapido per avviare un server di sviluppo locale è utilizzare il server integrato di Python.

  1. Utilizzando una riga di comando, dalla directory che contiene il file index.html, esegui:

    python -m http.server 8000

  2. In un browser web, vai alla pagina http://localhost:8000/

    Puoi anche utilizzare qualsiasi altro server web, ad esempio Apache HTTP Server.

Crea un video player

Innanzitutto, modifica dai.html per creare un elemento video HTML5 e un div da utilizzare per il clickthrough. L'esempio seguente importa l'SDK IMA DAI. Per maggiori dettagli, consulta la pagina Importa l'SDK IMA DAI.

Inoltre, aggiungi i tag necessari per caricare i file dai.css e dai.js, nonché per importare il video player hls.js. Poi, modifica dai.css per specificare le dimensioni e la posizione degli elementi della pagina. Infine, in dai.js, definisci le variabili per contenere le informazioni sulla richiesta di stream, una funzione initPlayer() da eseguire al caricamento della pagina e configura il pulsante di riproduzione per richiedere uno stream al clic.

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

Per riprendere la riproduzione durante le interruzioni pubblicitarie in pausa, configura i listener di eventi per gli eventi pause e start dell'elemento video in modo da mostrare e nascondere i controlli del player.

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

Carica l'SDK IMA DAI

Successivamente, aggiungi il framework IMA utilizzando un tag di script in dai.html, prima del tag per dai.js.

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

Inizializza StreamManager

Per richiedere un insieme di annunci, crea un ima.dai.api.StreamManager, che è responsabile della richiesta e della gestione degli stream DAI. Il costruttore accetta un elemento video e un elemento UI dell'annuncio per gestire i clic sugli annunci.

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

Invia una richiesta di stream

Definisci le funzioni per richiedere gli stream. Questo esempio include funzioni sia per i VOD che per i live streaming, che creano istanze della classe VODStreamRequest e della classe LiveStreamRequest. Dopo aver ottenuto l'istanza streamRequest, chiama il metodo streamManager.requestStream() con l'istanza della richiesta di stream.

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

Entrambi i metodi di richiesta di stream accettano una chiave API facoltativa. Se utilizzi uno stream protetto, devi creare una chiave di autenticazione DAI. Per maggiori dettagli, consulta Autentica le richieste di stream video DAI. Nessuno degli stream in questo esempio è protetto utilizzando una chiave di autenticazione DAI, pertanto apiKey non viene utilizzato.

Analizza i metadati dello stream

Devi anche aggiungere un gestore per ascoltare gli eventi di metadati temporizzati e inoltrarli alla classe StreamManager in modo che IMA emetta eventi annuncio durante le interruzioni pubblicitarie:

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

Questa guida utilizza il player hls.js per la riproduzione dello stream, ma l'implementazione dei metadati dipende dal tipo di player utilizzato.

Gestisci gli eventi di streaming

Implementa i listener di eventi per i principali eventi video. Questo esempio gestisce gli eventi LOADED, ERROR, AD_BREAK_STARTED e AD_BREAK_ENDED chiamando una funzione onStreamEvent(). Questa funzione gestisce il caricamento dello stream, gli errori dello stream e la disattivazione dei controlli del player durante la riproduzione degli annunci, come richiesto dall'SDK IMA.

/**
 * 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();
  });
}

Quando lo stream viene caricato, il video player carica e riproduce l'URL fornito utilizzando una funzione loadUrl().

È tutto. Ora richiedi e visualizzi gli annunci con l'SDK IMA DAI. Per scoprire funzionalità più avanzate dell'SDK, consulta le altre guide o gli esempi su GitHub.