Iniziare a utilizzare l'SDK IMA 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 della tua app.

Seleziona la soluzione DAI che ti interessa

Servizio completo Pubblicazione di pod

Pubblicazione di pod DAI

Questa guida illustra come riprodurre uno stream di pubblicazione di pod DAI per contenuti live o VOD, utilizzando l'SDK IMA DAI per HTML5 con un video player che si basa su hls.js per la riproduzione. Per visualizzare o seguire un'integrazione di esempio completata, con il supporto sia di HLS.js sia della riproduzione di Safari, consulta l'esempio di pubblicazione di pod HLS. Per il supporto di DASH.js, consulta l'esempio di pubblicazione di pod DASH. Puoi scaricare queste app di esempio dalla pagina di GitHub relativa alle release di HTML5 DAI.

Nota: l'SDK IMA DAI per HTML5 supporta sia gli stream HLS sia quelli DASH, ma la riproduzione di ciascuno richiede un media player o un'estensione diversa, come 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 IMA DASH.js per un punto di partenza per implementare gli stream DAI DASH con IMA.

Punto chiave: per utilizzare la pubblicazione di pod DAI, devi collaborare con un partner per la pubblicazione di pod e disporre di un account Ad Manager 360 Advanced. Se hai un account Ad Manager, contatta il tuo account manager per ulteriori dettagli. Per informazioni su come registrarti ad Ad Manager, visita il Centro assistenza Ad Manager.

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

Panoramica della pubblicazione di pod DAI

L'implementazione della pubblicazione di pod utilizzando l'SDK DAI IMA prevede due componenti principali, illustrati in questa guida:

• PodStreamRequest / PodVodStreamRequest: un oggetto che definisce una richiesta di stream ai server pubblicitari di Google. Le richieste specificano un codice rete e PodStreamRequest richiede anche una chiave asset personalizzata e una chiave API facoltativa. Entrambi includono altri parametri facoltativi.

• StreamManager: un oggetto che gestisce la comunicazione tra lo stream video e l'SDK DAI IMA, ad esempio l'invio di ping di monitoraggio e il inoltro di eventi stream al publisher.

Prerequisiti

Prima di iniziare, devi disporre di quanto segue:

• Tre file vuoti:

  • dai.html
  • dai.css
  • dai.js

• Python installato sul computer oppure un server web o un altro ambiente di sviluppo ospitato da utilizzare per i test

Configurare un ambiente di sviluppo

Poiché l'SDK 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. 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.

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

   Puoi anche utilizzare qualsiasi altro ambiente di sviluppo o server web ospitato, ad esempio Apache HTTP Server.

Creare un video player

Nota: questa guida presuppone che tu stia utilizzando la libreria HLS.js per riprodurre uno stream HLS. L'SDK IMA DAI per HTML5 può supportare anche gli stream DASH, con una libreria appropriata come Shaka Player o DASH.js.

Innanzitutto, modifica dai.html per creare un elemento video HTML5 e un elemento div da utilizzare per gli elementi dell'interfaccia utente dell'annuncio. 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.

Le costanti di richiesta di stream sono le seguenti:

• BACKUP_STREAM: un URL per uno stream di backup da riprodurre nel caso in cui il processo di pubblicazione degli annunci rileve un errore fatale.

• STREAM_URL: da utilizzare solo per i live streaming. L'URL dello stream video fornito dal tuo manipolatore del manifest o dal partner di terze parti che utilizza la pubblicazione di pod. Prima di effettuare una richiesta, dovrebbe essere richiesto di inserire l'ID stream fornito dall'SDK IMA DAI. In questo caso, l'URL dello stream include un segnaposto, [[STREAMID]], che viene sostituito con l'ID stream prima di effettuare una richiesta.

• NETWORK_CODE: il codice di rete per il tuo account Ad Manager 360.

• CUSTOM_ASSET_KEY: da utilizzare solo per i live streaming. La chiave dell'asset personalizzato che identifica l'evento di pubblicazione del pod in Ad Manager 360. Può essere creato dal tuo manipolatore del manifest o da un partner di terze parti per la pubblicazione di pod.

• API_KEY: da utilizzare solo per i live streaming. Una chiave API facoltativa che può essere obbligatoria per recuperare un ID stream dall'SDK DAI IMA.

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

// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";

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

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

Carica l'SDK IMA DAI

Aggiungi il framework DAI utilizzando un tag script in dai.html, prima del tag per dai.js.

Nota: per ricevere log della console più dettagliati, puoi sostituire ima3_dai.js con ima3_dai_debug.js. Tuttavia, ima3_dai_debug.js non deve essere utilizzato nelle app di produzione.

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 fai una richiesta di stream dal vivo o VOD

Pubblicazione di pod di live 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 riceve un elemento video e l'istanza risultante riceve un elemento UI dell'annuncio per gestire le interazioni con l'annuncio.

Poi, definisci una funzione per richiedere il live streaming del servizio di pod. Questa funzione dapprima crea un PodStreamRequest, lo configura con i parametri streamRequest forniti nel passaggio 2 e poi chiama streamManager.requestStream() con l'oggetto richiesta.

Punto chiave: nessuno degli stream in questo esempio è protetto, pertanto apiKey non viene utilizzato. Se lo stream richiede una chiave API, consulta Autenticare le richieste di video stream DAI.

dai.js

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

  requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}

function requestLivePodStream(networkCode, customAssetKey, apiKey) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving live Stream Request
  const streamRequest = new google.ima.dai.api.PodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.apiKey = apiKey;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Pubblicazione di pod VOD

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 l'istanza risultante riceve un elemento UI dell'annuncio per gestire le interazioni con l'annuncio.

Poi, definisci una funzione per richiedere lo stream VOD del servizio di pod. Questa funzione dapprima crea un PodVodStreamRequest, lo configura con i parametri streamRequest forniti nel passaggio 2 e poi chiama streamManager.requestStream() con l'oggetto richiesta.

dai.js

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

  requestVodPodStream(NETWORK_CODE);
}

function requestVodPodStream(networkCode) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving VOD Stream Request
  const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Gestire gli eventi stream

Pubblicazione di pod di live streaming

A questo punto, implementa gli ascoltatori di eventi per i principali eventi video. Questo esempio gestisce gli eventi STREAM_INITIALIZED, 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 loadStream().

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    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.STREAM_INITIALIZED:
      console.log('Stream initialized');
      loadStream(e.getStreamData().streamId);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream('');
      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 loadStream(streamID) {
  var url;
  if(streamID) {
    url = STREAM_URL.replace('[[STREAMID]]', streamID);
  } else {
    console.log('Stream Initialization Failed');
    url = BACKUP_STREAM;
  }
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
}

Pubblicazione di pod VOD

A questo punto, implementa gli ascoltatori di eventi per i principali eventi video. Questo esempio gestisce gli eventi STREAM_INITIALIZED, 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.

Inoltre, gli stream di pubblicazione di pod VOD richiedono l'uso della chiamata StreamManager.loadStreamMetadata() in risposta all'evento STREAM_INITIALIZED. Devi anche richiedere un URL stream al tuo partner di tecnologia video (VTP). Una volta che la chiamata loadStreamMetadata() è andata a buon fine, viene attivato un evento LOADED, in cui devi chiamare una funzione loadStream() con l'URL dello stream per caricarlo e riprodurlo.

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    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.STREAM_INITIALIZED:
      const streamId = e.getStreamData().streamId;
      // 'vtpInterface' is a place holder for your own video technology
      //  partner (VTP) API calls.
      vtpInterface.requestStreamURL({
        'streamId': streamId,
      })
      .then( (vtpStreamUrl) => {
        streamUrl = vtpStreamUrl;
        streamManager.loadStreamMetadata();
      }, (error) => {
        // Handle the error.
      });
      break;
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      loadStream(streamUrl);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream();
      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 loadStream(url) {
  if(url) {
    console.log('Loading:' + url);
    hls.loadSource(url);
  } else {
    console.log('Stream Initialization Failed');
    hls.loadSource(BACKUP_STREAM);
  }
  hls.attachMedia(videoElement);
}

Gestire i metadati dello stream

In questo passaggio implementi gli ascoltatori di eventi per i metadati per notificare all'SDK quando si verificano eventi correlati agli annunci. L'ascolto degli eventi dei metadati in-stream può variare a seconda del formato dello stream (HLS o DASH), del tipo di stream (live o VOD), del tipo di player e del tipo di backend DAI utilizzato. Per saperne di più, consulta la nostra guida ai metadati con temporizzazione.

Formato dello stream HLS (live streaming e VOD, player HLS.js)

Se utilizzi un player HLS.js, ascolta l'evento FRAG_PARSING_METADATA HLS.js per ottenere i metadati ID3 e trasmetterli all' SDK con StreamManager.processMetadata().

Per riprodurre automaticamente il video dopo che tutto è stato caricato e pronto, ascolta l'evento MANIFEST_PARSED di HLS.js per attivare la riproduzione.

function loadStream(streamID) {
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  
  // Timed metadata is passed HLS stream events to the streamManager.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
  hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}

function parseID3Events(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((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
}

function startPlayback() {
  console.log('Video Play');
  videoElement.play();
}

DASH.js (formato degli stream DASH, tipo di stream live e VOD)

Se utilizzi un player DASH.js, devi utilizzare stringhe diverse per ascoltare i metadati ID3 per gli stream live o VOD:

• Live streaming: 'https://developer.apple.com/streaming/emsg-id3'
• Stream di VOD: 'urn:google:dai:2018'

Passa i metadati ID3 all'SDK con StreamManager.processMetadata().

Per mostrare automaticamente i controlli video dopo che tutto è stato caricato e reso disponibile, ascolta l'evento MANIFEST_LOADED di DASH.js.

const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);

function processMetadata(metadataEvent) {
  const messageData = metadataEvent.event.messageData;
  const timestamp = metadataEvent.event.calculatedPresentationTime;

  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with dash.js.
  streamManager.processMetadata('ID3', messageData, timestamp);
}

function loadlistener() {
  showControls();

  // This listener must be removed, otherwise it triggers as addional
  // manifests are loaded. The manifest is loaded once for the content,
  // but additional manifests are loaded for upcoming ad breaks.
  dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}

Shaka Player con live streaming (formato stream DASH)

Se utilizzi Shaka Player per la riproduzione di live streaming, utilizza la stringa 'emsg' per ascoltare gli eventi relativi ai metadati. Poi, utilizza i dati del messaggio dell'evento nella chiamata a StreamManager.onTimedMetadata().

shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));

function onEmsgEvent(metadataEvent) {
  // Use StreamManager.onTimedMetadata() if your video player provides
  // processed metadata, as with Shaka player livestreams.
  streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}

Shaka Player con stream VOD (formato stream DASH)

Se utilizzi Shaka Player per la riproduzione di stream VOD, utilizza la stringa 'timelineregionenter' per ascoltare gli eventi dei metadati. Poi, utilizza i dati del messaggio dell'evento nella chiamata a StreamManager.processMetadata() con la stringa 'urn:google:dai:2018'.

shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));

function onTimelineEvent(metadataEvent) {
  const detail = metadataEvent.detail;
  if ( detail.eventElement.attributes &&
       detail.eventElement.attributes['messageData'] &&
       detail.eventElement.attributes['messageData'].value ) {
        const mediaId = detail.eventElement.attributes['messageData'].value;
        const pts = detail.startTime;
        // Use StreamManager.processMetadata() if your video player provides raw
        // ID3 tags, as with Shaka player VOD streams.
        streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
       }
}

Gestire gli eventi dei giocatori

Aggiungi listener di eventi agli eventi pause e start dell'elemento video per consentire all'utente di riprendere la riproduzione quando l'SDK si mette in pausa durante le interruzioni pubblicitarie.

function loadStream(streamUrl) {
  ...
  
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);
}

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

Ripulire gli asset DAI IMA

Una volta completata la richiesta e la visualizzazione degli annunci in uno streaming di pubblicazione di pod con l'SDK DAI IMA, ti consigliamo di ripulire le risorse al termine della sessione di pubblicazione di pod. Chiama StreamManager.destroy() per interrompere la riproduzione dello stream, interrompere tutto il monitoraggio degli annunci e rilasciare tutti gli asset stream caricati.

Per scoprire di più sulle funzionalità dell'SDK più avanzate, consulta le altre guide o i sample su GitHub.