Inizia

Gli SDK IMA ti consentono di integrare facilmente gli 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 inviano una richiesta di streaming per annunci e contenuti video, VOD o contenuti in diretta. L'SDK restituisce quindi un video stream combinato, in modo che tu non debba gestire il passaggio da un annuncio all'altro all'interno della tua app.

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

Panoramica dell'IMA DAI

L'implementazione dell'inserimento di annunci dinamici IMA prevede due componenti principali dell'SDK, illustrati in questa guida:

  • StreamRequest: VODStreamRequest o LiveStreamRequest: un oggetto che definisce una richiesta di streaming. Le richieste di stream possono essere video on demand o live streaming. Le richieste specificano un ID contenuto, una chiave API o un token di autenticazione e altri parametri.
  • StreamManager: un oggetto che gestisce i flussi di inserimento di annunci dinamici e le interazioni con il backend DAI. Inoltre, gestisce i ping di monitoraggio e inoltra gli eventi in streaming e gli annunci al publisher.

Prerequisiti

Prima di iniziare, assicurati di disporre di:

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

1. Avvia un server di sviluppo

Poiché l'SDK IMA carica le dipendenze tramite lo stesso protocollo della pagina da cui è caricato, 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.

  1. Utilizzando una riga di comando, dalla directory contenente il tuo file index.html viene eseguito:

    python -m http.server 8000
    
  2. In un browser web, vai a http://localhost:8000/

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

2. 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 anche i tag necessari per caricare i file dai.css e dai.js, oltre a 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 conservare le informazioni della richiesta di streaming 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'

// Live stream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2528370";
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');
}

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

...

4. Inizializza StreamManager ed effettua una richiesta di streaming

Per richiedere un insieme di annunci, crea un elemento ima.dai.api.StreamManager, responsabile della richiesta e della gestione degli stream DAI. Il costruttore acquisisce un elemento video, mentre l'istanza risultante utilizza un elemento UI per gestire i clic sull'annuncio.

Definisci quindi le funzioni che richiedono gli stream. Questo esempio include funzioni per sia VOD sia live streaming, che creano istanze di VODStreamRequest e LiveStreamRequest rispettivamente e quindi chiamano streamManager.requestStream() con i parametri streamRequest. Per i live streaming, devi anche aggiungere un gestore per ascoltare gli eventi di metadati a tempo e inoltrare gli eventi a StreamManager. Puoi inserire un commento o un commento per adattarlo al tuo caso d'uso. Entrambi i metodi richiedono una chiave API facoltativa. Se utilizzi uno stream criptato, devi creare una chiave di autenticazione DAI.

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

5. Gestire gli eventi di streaming

Infine, devi implementare i listener di eventi per gli eventi video principali. Questo semplice esempio gestisce gli eventi LOADED, ERROR, AD_BREAK_STARTED e AD_BREAK_ENDED chiamando una funzione onStreamEvent(). Questa funzione consente di gestire il caricamento e gli errori del flusso, nonché di disattivare i controlli del player durante la riproduzione di un annuncio, operazione richiesta dall'SDK. Quando il flusso viene caricato, il video player carica e riproduce l'URL fornito utilizzando una funzione loadUrl().

Dovrai inoltre impostare i listener di eventi per gli eventi pause e start dell'elemento video per consentire all'utente di riprendere la riproduzione quando l'IMA viene messo in pausa durante le interruzioni pubblicitarie.

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