Gestire i metadati a tempo

Seleziona la piattaforma: HTML5 Roku

L'SDK Interactive Media Ads (IMA) Dynamic Ad Insertion (DAI) si basa su informazioni sui metadati incorporate nei segmenti multimediali dello stream (metadati in banda) o nel file manifest dello streaming (metadati nel manifest) per monitorare le posizioni degli spettatori e gli eventi pubblicitari 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'ora pianificata o in batch. Ogni stringa di metadati ha un timestamp di presentazione (PTS) associato per il momento in cui 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 le stringhe di metadati pronte per l'elaborazione all'SDK. Accetta un solo argomento:

  • metadata: un oggetto contenente una chiave di TXXX con un valore stringa associato che ha come 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 devono essere elaborati i dati.

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

Stream HLS MPEG2TS

I flussi HLS DAI lineari che utilizzano segmenti MPEG2TS trasmettono metadati temporizzati al video player tramite tag ID3 in banda. Questi tag ID3 sono incorporati nei segmenti MPEG2TS e hanno il nome del campo TXXX (per 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. È possibile 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 PTS corrispondenti. Non è necessario decodificare i dati di esempio dall'array di byte alla stringa o filtrare i tag ID3 irrilevanti, poiché l'SDK IMA DAI esegue automaticamente questa decodifica e questo filtro.

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 CMAF HLS

Gli stream HLS di DAI lineare che utilizzano Common Media Application Framework (CMAF) trasmettono metadati temporizzati tramite caselle eMSGv1 in banda seguendo lo standard ID3 tramite CMAF. Questi riquadri eMSG sono incorporati all'inizio di ogni segmento multimediale e ogni eMSG ID3 contiene un PTS relativo all'ultima discontinuità nel flusso.

A partire dalla versione 1.2.0 di HLS.js, entrambi i nostri 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 valere per 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. È possibile trasferire tutti i metadati all'SDK IMA DAI, indipendentemente dal fatto che siano pertinenti alla sincronizzazione o meno. Tutti i metadati non correlati all'inserimento di annunci dinamici 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 considera i metadati ID3 tramite eMSG come pseudo eventi 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 PTS corrispondenti. Non è necessario decodificare i dati di esempio dall'array di byte alla stringa, poiché l'SDK IMA DAI esegue questa decodifica automaticamente.

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 un flusso di eventi con il valore personalizzato schemeIdUri 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, quindi spetta a te 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 mostra 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à dei dettagli 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 di pod, esistono configurazioni diverse per il trasferimento dei metadati temporizzati a seconda dei seguenti criteri:

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

Formato dello stream HLS (stream live e VOD, lettore 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 rilevare i metadati ID3 per gli stream live o VOD:

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

Trasferisci 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 di streaming DASH)

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

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