Configurare l'SDK IMA per DAI

Gli SDK IMA semplificano l'integrazione di annunci multimediali nei tuoi siti web e nelle tue app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK IMA DAI, le app effettuano una richiesta di streaming per l'annuncio e il video dei contenuti, che possono essere VOD o live. L'SDK restituisce quindi uno stream video combinato, in modo da non dover gestire il passaggio tra l'annuncio e il video di contenuti all'interno dell'app.

Seleziona la soluzione DAI che ti interessa

Servizio completo Servizio pod

DAI con servizio completo

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

Nota:L'SDK IMA DAI per HTML5 supporta gli stream HLS e DASH, ma la riproduzione di ciascuno richiede un lettore multimediale o un'estensione diversa, ad esempio HLS.js o DASH.js, con implementazioni diverse.

Questa guida spiega come configurare HLS.js e l'SDK IMA DAI per riprodurre uno stream HLS, con note importanti sulle differenze di implementazione per DASH.

Consulta l'app di esempio DASH.js di IMA per un punto di partenza per implementare stream DAI DASH con IMA.

Per utilizzare IMA DAI, devi disporre di un account Ad Manager 360 Advanced. Se hai un account Ad Manager, contatta il tuo account manager per maggiori dettagli. Per informazioni sull'iscrizione ad Ad Manager, visita il Centro assistenza Ad Manager.

Nota:per informazioni sull'integrazione con altre piattaforme o sull'utilizzo degli SDK IMA lato client, consulta SDK Interactive Media Ads.

Panoramica di IMA DAI

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

• StreamRequest: un VODStreamRequest o un LiveStreamRequest: un oggetto che definisce una richiesta di flusso. 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 l'SDK IMA per gestire gli identificatori pubblicità come specificato nelle impostazioni di Google Ad Manager.
• StreamManager: Un oggetto che gestisce i flussi di inserimento di annunci dinamici e le interazioni con il backend DAI. Lo stream manager 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

Avviare un server di sviluppo

Poiché l'SDK IMA DAI carica le dipendenze utilizzando lo stesso protocollo della pagina da cui viene caricata, devi utilizzare un web server 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

   Nota: http.server è disponibile solo in Python 3.x.

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

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

Creare 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 Importare 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 della 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>

dai.html

#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}
dai.css

// 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';
  });
}
dai.js

Per riprendere la riproduzione durante le interruzioni pubblicitarie in pausa, configura i listener di eventi per gli eventi pause e start dell'elemento video per 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';
}
dai.js

Carica l'SDK IMA DAI

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

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

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 dell'interfaccia utente 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);
}
dai.js

Effettuare una richiesta di stream

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

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

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 Autenticare le richieste di video stream DAI. Nessuno stream in questo esempio è protetto utilizzando una chiave di autenticazione DAI, quindi apiKey non viene utilizzato.

Analizza i metadati dello stream

Devi anche aggiungere un gestore per ascoltare gli eventi di metadati temporizzati e inoltrare gli eventi alla classe StreamManager per consentire a IMA di generare eventi pubblicitari 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);
      });
    }
  });
}
dai.js

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

Gestire gli eventi di stream

Implementa i listener di eventi per gli eventi video principali. 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();
  });
}
dai.js

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 di più sulle funzionalità avanzate dell'SDK, consulta le altre guide o gli esempi su GitHub.