Iniziare a utilizzare l'SDK IMA DAI

Gli SDK IMA semplificano l'integrazione degli annunci multimediali nei siti web e nelle app. Gli SDK IMA possono richiedi 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 gli annunci e i video di contenuti, sia VOD che dal vivo. L'SDK restituisce quindi video stream combinati, in modo che non sia necessario gestire il passaggio dall'annuncio ai video di contenuti e viceversa all'interno dell'app.

Seleziona la soluzione DAI che ti interessa

DAI servizio completo

Questa guida illustra come integrare l'SDK IMA DAI in un semplice video dell'app. Se vuoi visualizzare o seguire un campione completo integrazione, scarica semplice esempio tratto da GitHub.

Panoramica dell'inserimento di annunci dinamici in IMA

L'implementazione dell'SDK IMA DAI coinvolge due componenti principali, come dimostrato in 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 specificano un ID contenuto, nonché 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 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 su 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. Tramite 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, come Apache HTTP o server.

Creare un video player semplice

In primo luogo, modifica dai.html per creare un semplice elemento video HTML5 e un div per utilizzare per il clickthrough. 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 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 DAI 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 DAI

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 ed effettua una richiesta di stream

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

Poi definisci le funzioni che richiedono gli stream. Questo esempio include le funzioni per sia VOD che live streaming, che creano istanze di VODStreamRequest e Rispettivamente LiveStreamRequest, quindi chiama streamManager.requestStream() con i parametri streamRequest. Per i live streaming, devi anche aggiungere un gestore per ascoltare gli eventi dei metadati con temporizzazione e inoltrarli a StreamManager. Puoi commentare o annullare il commento del codice in base al tuo caso d'uso. Entrambi i metodi richiedono una chiave API facoltativa. Se utilizzi uno stream protetto, necessario crea una chiave di autenticazione DAI.

Nessuno stream in questo esempio è protetto, quindi apiKey non viene utilizzato.

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 stream

Infine, devi implementare gli ascoltatori 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 gestisce il caricamento e gli errori dello stream, nonché la disattivazione dei controlli del player durante la riproduzione di un annuncio, come richiesto dall'SDK. Quando lo stream viene caricato, il video player carica e riproduce l'URL fornito utilizzando una funzione loadUrl().

Ti consigliamo inoltre di configurare listener di eventi per l'elemento pause dell'elemento video e start eventi per consentire all'utente di riprendere la riproduzione quando l'IMA mette in pausa durante le interruzioni pubblicitarie.

Per poter usare l'inserimento di annunci dinamici, il player personalizzato deve trasmettere gli eventi ID3 per i live streaming. agli SDK IMA DAI 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 DAI. A per saperne di più sulle funzioni avanzate dell'SDK, consulta le altre guide o su GitHub.