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 richiesta di streaming per annunci e contenuti video, sia VOD che contenuti 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 pubblicazione pod

Questa guida illustra come riprodurre uno stream con pubblicazione di pod DAI per i contenuti dal vivo o VOD utilizzando l'SDK IMA DAI per HTML5 con un video player che si basa su hls.js per la riproduzione. Se vuoi visualizzare o seguire un campione completo integrazione, con il supporto sia per HLS.js sia per Safari Riproduzione, consulta le Esempio di pubblicazione di pod HLS. Per il supporto di DASH.js, vedi l'esempio di pubblicazione dei pod DASH. Puoi scaricare queste app di esempio dalla release GitHub DAI HTML5 .

Panoramica della pubblicazione di pod DAI

L'implementazione della pubblicazione dei pod utilizzando l'SDK IMA DAI prevede due componenti principali: vengono illustrate in questa guida:

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

• StreamManager: un oggetto che gestisce la comunicazione tra lo stream video e l'SDK IMA DAI, come l'attivazione dei ping di monitoraggio e inoltrare gli eventi di streaming al publisher.

Prerequisiti

Prima di iniziare, è necessario quanto segue:

• Tre file vuoti:

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

• Python installato sul tuo computer, un server web o un altro strumento di sviluppo in hosting da usare per eseguire test

Configurare un ambiente di sviluppo

Poiché l'SDK carica le dipendenze utilizzando lo stesso protocollo della pagina da cui viene caricata, devi usare un server web per testare l'app. Un breve per avviare un server di sviluppo locale consiste nell'utilizzare il server integrato di Python.

1. Tramite una riga di comando, dalla directory che contiene index.html esecuzione del file:

   python -m http.server 8000
   

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

   Puoi anche utilizzare qualsiasi altro ambiente di sviluppo in hosting o server web, come Apache HTTP Server.

Creare un video player semplice

In primo luogo, modifica dai.html per creare un semplice elemento video HTML5 e un div per gli elementi dell'interfaccia utente dell'annuncio. Aggiungi anche i tag necessari per caricare il file dai.css. e dai.js, oltre a importare il video player hls.js.

Quindi, modifica dai.css per specificare le dimensioni e la posizione degli elementi della pagina. Infine, in dai.js, definisci le variabili in cui memorizzare le informazioni della richiesta di streaming. e una funzione initPlayer() da eseguire al caricamento della pagina.

Le costanti delle richieste di flussi di dati sono le seguenti:

• BACKUP_STREAM: un URL per uno stream di backup da riprodurre nel caso in cui l'annuncio venga elaborato rileva un errore irreversibile.

• STREAM_URL: utilizzato solo per i live streaming. L'URL dello stream video fornito manipolatore del manifest o partner di terze parti utilizzando la pubblicazione dei pod. Dovrebbe è necessario inserire l'ID stream fornito dall'SDK IMA DAI prima di invia una richiesta. In questo caso, l'URL dello stream include un segnaposto, [[STREAMID]], che viene sostituito con l'ID streaming prima di effettuare una richiesta.

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

• CUSTOM_ASSET_KEY: utilizzato solo per i live streaming. La chiave asset personalizzata identifica l'evento di pubblicazione di pod in Ad Manager 360. Può essere creato il manipolatore del manifest o il partner per la pubblicazione di pod di terze parti.

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

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

In seguito, aggiungi il framework DAI 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 streaming dal vivo o VOD

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

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 di streaming

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

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 degli stream

In questo passaggio implementerai i listener di eventi per i metadati per inviare una notifica all'SDK quando si verificano eventi annuncio. L'ascolto di eventi di metadati in-stream può variare a seconda del il formato dello stream (HLS o DASH), il tipo di stream (streaming live o VOD), il tipo di player e il tipo di backend DAI utilizzato. Consulta le nostre Metadati per ulteriori informazioni.

Formato di stream HLS (streaming live 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 passarli al SDK con StreamManager.processMetadata().

Per riprodurre automaticamente il video dopo che tutto è stato caricato e pronto, ascolta l'evento MANIFEST_PARSED 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 di streaming DASH, tipo di stream live e tipo di stream VOD)

Se utilizzi un player DASH.js, devi usare stringhe diverse per ascoltare i metadati ID3 per i contenuti dal vivo o VOD stream:

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

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

Per mostrare automaticamente i controlli video dopo che tutti sono stati caricati e pronti, rimanere in ascolto dell'evento MANIFEST_LOADED 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 di stream DASH)

Se usi il player di Shaka per la riproduzione in live streaming, utilizza la stringa 'emsg' per ascoltare gli eventi dei metadati. Quindi, utilizza i dati dei messaggi di 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});
}

Player Shaka con stream VOD (formato stream DASH)

Se usi il player di Shaka per Riproduzione in streaming VOD, utilizza la stringa 'timelineregionenter' da ascoltare e i relativi eventi di metadati. Quindi, utilizza i dati dei messaggi di evento nella chiamata per 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

Per consentire l'aggiunta dei listener di eventi agli eventi pause e start dell'elemento video, all'utente di riprendere la riproduzione quando l'SDK viene messo 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';
  }
}

È tutto. Ora stai richiedendo e visualizzando gli annunci in un pod che pubblica lo stream con l'SDK IMA DAI per HTML5. Per scoprire altre funzioni avanzate dell'SDK, consulta altre guide o gli esempi su GitHub.