Questa pagina è stata tradotta dall'API Cloud Translation.

Configurare l'SDK IMA per DAI

Gli SDK IMA semplificano l'integrazione degli annunci multimediali nei tuoi siti web e nelle tue app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server conforme a VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK IMA DAI, le app inviano una richiesta di streaming per gli annunci e i video di contenuti, sia VOD che dal vivo. L'SDK restituisce quindi un stream video combinato, in modo da non dover gestire il passaggio tra annunci e video di contenuti all'interno dell'app.

Seleziona la soluzione DAI che ti interessa

DAI con servizio completo

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

Panoramica dell'inserimento di annunci dinamici in IMA

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 dello stream gestisce anche i ping di monitoraggio e inoltra gli eventi relativi allo stream e agli 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.

Utilizzando una riga di comando, dalla directory contenente il file index.html, esegui:
```
python -m http.server 8000
```
Nota: http.server è disponibile solo in Python 3.x.
In un browser web, vai a 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 elemento div da utilizzare per il clickthrough. L'esempio seguente importa l'SDK IMA DAI. Per maggiori dettagli, consulta Importare l'SDK IMA DAI.

Aggiungi anche 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 in modo che richieda 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 gli ascoltatori 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

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 riceve 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

Inviare una richiesta di streaming

Definisci le funzioni per richiedere gli stream. Questo esempio include funzioni sia per i VOD sia per i 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 di 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);
}dai.js

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

Analizza i metadati dello stream (solo live streaming)

Per i live streaming, devi anche aggiungere un gestore per ascoltare gli eventi dei metadati con temporizzazione e inoltrarli alla classe StreamManager affinché IMA possa emettere gli eventi correlati agli annunci durante le interruzioni pubblicitarie:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Only used in LIVE streams. 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 player hls.js per la riproduzione in streaming, ma l'implementazione dei metadati dipende dal tipo di player utilizzato.

Gestire gli eventi stream

Implementa gli ascoltatori 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 dell'annuncio, 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 approfondire le funzionalità SDK più avanzate, consulta le altre guide o i sample su GitHub.