Questa pagina è stata tradotta dall'API Cloud Translation.

Iniziare a utilizzare l'SDK IMA 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 annunci e contenuti video, VOD o contenuti dal vivo. L'SDK restituisce quindi un video stream combinato, in modo che tu non debba gestire il passaggio tra l'annuncio e i contenuti video all'interno dell'app.

Seleziona la soluzione DAI che ti interessa

DAI servizio completo

Questa guida illustra come integrare l'SDK IMA in una semplice app per video player. Per visualizzare o seguire un'integrazione di esempio completata, scarica questo esempio semplice da GitHub.

Panoramica dell'IMA DAI

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

StreamRequest—VODStreamRequest o LiveStreamRequest: un oggetto che definisce una richiesta di flusso. Le richieste di streaming possono riguardare video on demand o live streaming. Le richieste specificano un Content ID, una chiave API o un token di autenticazione e altri parametri.
StreamManager: un oggetto che gestisce gli stream di inserimento di annunci dinamici e le interazioni con il backend DAI. Il gestore dello streaming gestisce anche i ping di monitoraggio e inoltra gli eventi live e degli 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 carica le dipendenze utilizzando lo stesso protocollo della pagina da cui vengono caricate, devi utilizzare un server web per testare l'app. Il modo più semplice per avviare un server di sviluppo locale è utilizzare il server integrato di Python.

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

Innanzitutto, modifica dai.html per creare un semplice elemento video HTML5 e un div da utilizzare per il clickthrough. Aggiungi inoltre 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 la dimensione e la posizione degli elementi della pagina. Infine, in dai.js, definisci le variabili che contengono le informazioni relative alla richiesta di stream e una funzione initPlayer() da eseguire al caricamento della pagina.

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 SDK DAI 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'

// Livestream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2548831";
var TEST_VIDEO_ID = "tears-of-steel";

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;
var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

Carica l'SDK IMA

Poi, aggiungi il framework IMA utilizzando un tag script in dai.html, prima del tag per 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>

Inizializza StreamManager e invia una richiesta di streaming

Per richiedere un insieme di annunci, crea un ima.dai.api.StreamManager, che è responsabile della richiesta e della gestione degli stream DAI. Il costruttore prende un elemento video e l'istanza risultante utilizza un elemento dell'interfaccia utente per gli annunci per gestire i clic sugli annunci.

Quindi, definisci le funzioni che richiedono flussi di dati. Questo esempio include funzioni sia per VOD che live streaming, che creano istanze rispettivamente di VODStreamRequest e LiveStreamRequest e quindi chiamano streamManager.requestStream() con i parametri streamRequest. Per i live streaming, devi anche aggiungere un gestore per ascoltare gli eventi di metadati con timestamp e inoltrare gli eventi a StreamManager. Puoi commentare o rimuovere il commento al codice in base al tuo caso d'uso. Entrambi i metodi accettano una chiave API facoltativa. Se utilizzi un flusso protetto, devi creare una chiave di autenticazione DAI.

Nessuno dei due stream in questo esempio è protetto, pertanto non viene utilizzato apiKey.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  // Timed metadata is only used for LIVE streams.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(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(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, null);
  // Uncomment the line below and comment out the one above to request a
  // LIVE stream instead of a VOD stream.
  //requestLiveStream(TEST_ASSET_KEY, null);
}

function requestVODStream(cmsId, videoId, apiKey) {
  var streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

function requestLiveStream(assetKey, apiKey) {
  var streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

Gestire gli eventi di streaming

Infine, devi implementare i listener di eventi per i principali eventi video. Questo semplice esempio gestisce gli eventi LOADED, ERROR, AD_BREAK_STARTED e AD_BREAK_ENDED richiamando una funzione onStreamEvent(). Questa funzione gestisce il caricamento degli stream e gli errori, nonché la disattivazione dei controlli del player durante la riproduzione di un annuncio, come richiesto dall'SDK. Quando viene caricato lo stream, il video player carica e riproduce l'URL fornito utilizzando una funzione loadUrl().

Potresti voler impostare anche listener di eventi per gli eventi pause e start dell'elemento video in modo da consentire all'utente di riprendere la riproduzione quando l'IMA viene messa in pausa durante le interruzioni pubblicitarie.

Per poter utilizzare l'inserimento di annunci dinamici, il player personalizzato deve trasmettere gli eventi ID3 per i live streaming agli SDK IMA come mostrato nel codice di esempio.

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);

  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.LOADED,
     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.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');
      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 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();
  });
}

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

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