Gestire i metadati a tempo

Seleziona la piattaforma: HTML5 Roku

L'SDK Interactive Media Ads (IMA) per l'inserimento di annunci dinamici (DAI) si basa sulle informazioni dei metadati incorporate nei segmenti multimediali dello stream (metadati in-band) o nel file manifest dello streaming (metadati in-manifest) per monitorare le posizioni degli spettatori e gli eventi degli annunci lato client. I metadati vengono inviati in formati diversi, a seconda del tipo di stream riprodotto.

Il video player riceve i metadati temporizzati in batch. A seconda del player, i metadati possono essere visualizzati all'orario pianificato o in batch. Ogni stringa di metadati ha un timestamp di presentazione (PTS) associato per quando deve essere attivata.

La tua app è responsabile dell'acquisizione dei metadati e del loro inoltro all'SDK IMA DAI. L'SDK offre i seguenti metodi per trasmettere queste informazioni:

onTimedMetadata

Questo metodo inoltra all'SDK le stringhe di metadati pronte per l'elaborazione. Accetta un singolo argomento:

  • metadata: un oggetto contenente una chiave TXXX con un valore stringa associato con il prefisso google_.
processMetadata

Questo metodo pianifica l'elaborazione delle stringhe di metadati da parte dell'SDK dopo il PTS specificato. Accetta i seguenti argomenti:

  • type: una stringa contenente il tipo di evento in fase di elaborazione. I valori accettati sono ID3 per HLS o urn:google:dai:2018 per DASH
  • data: un valore stringa con il prefisso google_ o un array di byte che segue questo formato ID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxx.
  • timestamp: il timestamp in secondi in cui i dati devono essere elaborati.

Ogni tipo di stream supportato dall'SDK IMA DAI utilizza una forma univoca di metadati temporizzati, come descritto nelle sezioni seguenti.

Stream HLS MPEG2TS

Gli stream HLS DAI lineari che utilizzano i segmenti MPEG2TS trasmettono i metadati temporizzati al video player tramite i tag ID3 in-band. Questi tag ID3 sono incorporati nei segmenti MPEG2TS e viene assegnato il nome del campo TXXX (per i contenuti di testo personalizzati definiti dall'utente).

Riproduzione in Safari

Safari elabora automaticamente i tag ID3 come traccia nascosta, in modo che gli eventi cuechange vengano attivati al momento giusto per elaborare ogni parte dei metadati. Puoi trasmettere tutti i metadati all'SDK IMA DAI, indipendentemente dal contenuto o dal tipo. I metadati non pertinenti vengono filtrati automaticamente.

Ecco un esempio:

videoElement.textTracks.addEventListener('addtrack', (e) => {
  const track = e.track;
  if (track.kind === 'metadata') {
    track.mode = 'hidden';
    track.addEventListener('cuechange', () => {
      for (const cue of track.activeCues) {
        const metadata = {};
        metadata[cue.value.key] = cue.value.data;
        streamManager.onTimedMetadata(metadata);
      }
    });
  }
});
...

HLS.js

HLS.js fornisce i tag ID3 in batch tramite l'evento FRAG_PARSING_METADATA, come array di campioni. HLS.js non traduce i dati ID3 dagli array di byte alle stringhe e non compensa gli eventi con i relativi PTS. Non è necessario decodificare i dati di esempio dall'array di byte alla stringa o filtrare i tag ID3 non pertinenti, poiché l'SDK IMA DAI esegue automaticamente la decodifica e il filtraggio.

Ecco un esempio:

hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
  if (streamManager && data) {
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
});
...

Stream HLS CMAF

Gli stream HLS DAI lineari che utilizzano il Common Media Application Framework (CMAF) trasmettono i metadati temporizzati tramite le caselle eMSGv1 in-band seguendo lo standard ID3 tramite CMAF. Queste caselle eMSG sono incorporate all'inizio di ogni segmento multimediale e ogni eMSG ID3 contiene un PTS relativo all'ultima discontinuità nello stream.

A partire dalla release 1.2.0 di HLS.js, entrambi i player suggeriti trasmettono ID3 tramite CMAF all'utente come se fossero tag ID3. Per questo motivo, gli esempi seguenti sono gli stessi degli stream HLS MPEG2TS. Tuttavia, questo potrebbe non essere il caso di tutti i player, quindi l'implementazione del supporto per gli stream HLS CMAF potrebbe richiedere un codice univoco per analizzare ID3 tramite eMSG.

Riproduzione in Safari

Safari tratta i metadati ID3 tramite eMSG come eventi pseudo ID3, fornendoli in batch, automaticamente, come traccia nascosta, in modo che gli eventi cuechange vengano attivati al momento giusto per elaborare ogni parte dei metadati. Puoi trasmettere tutti i metadati all'SDK IMA DAI, indipendentemente dal fatto che siano pertinenti alla tempistica o meno. I metadati non correlati a DAI vengono filtrati automaticamente.

Ecco un esempio:

videoElement.textTracks.addEventListener('addtrack', (e) => {
  const track = e.track;
  if (track.kind === 'metadata') {
    track.mode = 'hidden';
    track.addEventListener('cuechange', () => {
      for (const cue of track.activeCues) {
        const metadata = {};
        metadata[cue.value.key] = cue.value.data;
        streamManager.onTimedMetadata(metadata);
      }
    });
  }
});
...

HLS.js

A partire dalla versione 1.2.0, HLS.js tratta i metadati ID3 tramite eMSG come eventi pseudo ID3, fornendoli in batch, tramite l'evento FRAG_PARSING_METADATA, come array di campioni. HLS.js non traduce i dati ID3 dagli array di byte alle stringhe e non compensa gli eventi con i relativi PTS. Non è necessario decodificare i dati di esempio dall'array di byte alla stringa, poiché l'SDK IMA DAI esegue automaticamente la decodifica.

Ecco un esempio:

hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
  if (streamManager && data) {
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
});
...

Stream DASH

Gli stream DASH DAI lineari trasmettono i metadati come eventi manifest in uno stream di eventi con il valore schemeIdUri personalizzato urn:google:dai:2018. Ogni evento in questi stream contiene un payload di testo e il PTS.

DASH.js

Dash.js fornisce gestori di eventi personalizzati denominati in base al valore schemeIdUri di ogni stream di eventi. Questi gestori personalizzati vengono attivati in batch, lasciando a te il compito di elaborare il valore PTS per sincronizzare correttamente l'evento. L'SDK IMA DAI può gestire questa operazione per te, con il metodo streamManager, processMetadata().

Ecco un esempio:

const dash = dashjs.MediaPlayer().create();
dash.on('urn:google:dai:2018', (payload) => {
  const mediaId = payload.event.messageData;
  const pts = payload.event.calculatedPresentationTime;
  streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
});
...

Shaka Player

Shaka Player visualizza gli eventi come parte dell'evento timelineregionenter. A causa di un'incompatibilità di formattazione con Shaka Player, il valore dei metadati deve essere recuperato in formato non elaborato, tramite la proprietà detail eventNode.attributes['messageData'].

Ecco un esempio:

player.addEventListener('timelineregionenter', function(event) {
  const detail = event.detail;
  if ( detail.eventNode.attributes &&
       detail.eventNode.attributes['messageData']) {
    const mediaId = detail.eventNode.attributes['messageData'];
    const pts = detail.startTime;
    streamManager.processMetadata("urn:google:dai:2018", mediaId, pts);
  }
});
...

Pubblicazione dei pod

Per la pubblicazione dei pod, esistono diverse configurazioni per la trasmissione dei metadati temporizzati a seconda dei seguenti criteri:

  • Tipo di stream live o VOD
  • Formato dello stream HLS o DASH
  • Il tipo di player utilizzato
  • Il tipo di backend DAI utilizzato

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

Se utilizzi un player HLS.js, ascolta l'evento FRAG_PARSING_METADATA di HLS.js per ottenere i metadati ID3 e trasmettili 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 streams:

  • 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 tutto è stato caricato e pronto, 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 degli stream DASH)

Se utilizzi Shaka Player per la riproduzione di live streaming, utilizza la stringa 'emsg' per ascoltare gli eventi dei metadati. Quindi, 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 degli stream DASH)

Se utilizzi Shaka Player per la riproduzione di stream VOD, utilizza la stringa 'timelineregionenter' per ascoltare gli eventi dei metadati. Quindi, 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);
       }
}