Questa pagina è stata tradotta dall'API Cloud Translation.

Gestire i metadati a tempo negli stream DAI lineari

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

Il video player riceve metadati sincronizzati in batch. A seconda del giocatore, i metadati possono essere mostrati all'ora pianificata o in batch. Ogni metadato ha un timestamp di presentazione (PTS) associato che indica quando deve essere attivata.

La tua app è responsabile dell'acquisizione dei metadati e dell'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 essere elaborate l'SDK. Prende un singolo argomento:

metadata: un oggetto contenente una chiave di TXXX con una stringa associata con prefisso google_.

processMetadata

Questo metodo pianifica le stringhe di metadati che devono essere elaborate dall'SDK dopo il parametro PTS specificato. Prende i seguenti argomenti:

type: una stringa contenente il tipo di evento da elaborare. Accettato i valori sono ID3 per HLS o urn:google:dai:2018 per DASH
data: un valore stringa preceduto da google_ o un array di byte che decodifica in una stringa di questo tipo.
timestamp: il timestamp in secondi in cui i dati devono essere elaborati.

Ogni tipo di stream supportato dall'SDK IMA DAI utilizza un tipo univoco di visualizzazione a tempo come descritto nelle sezioni seguenti.

Stream MPEG2TS HLS

Gli stream HLS DAI lineari utilizzando i segmenti MPEG2TS passano i metadati temporizzati alla tramite tag ID3 in banda. Questi tag ID3 sono incorporati ai segmenti MPEG2TS, a cui viene assegnato il nome del campo TXXX (per il testo personalizzato contenuti).

Riproduzione in Safari

Safari elabora automaticamente i tag ID3, come una traccia nascosta, quindi gli eventi cuechange attivarsi al momento giusto per elaborare ogni parte dei metadati. Va bene passare tutti i metadati all'SDK IMA DAI, indipendentemente dal contenuto o dal tipo. Non pertinente 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 tag ID3 in batch tramite l'evento FRAG_PARSING_METADATA, sotto forma di array di campioni. HLS.js non traduce i dati ID3 da array di byte alle stringhe e non compensa gli eventi nel PTS corrispondente. Non è necessarie per decodificare i dati di esempio da array di byte a stringa o per filtrare tag ID3 non pertinenti, poiché l'SDK IMA DAI esegue questa decodifica e questo filtro 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);
    });
  }
});
...

Flussi CMAF HLS

Stream HLS DAI lineari con pass Common Media Application Framework (CMAF) metadati temporizzati tramite caselle eMSGv1 in banda che seguono ID3 e standard CMAF. Questi riquadri eMSG incorporato all'inizio di ciascun segmento multimediale, con ogni ID3 eMSG contenente un PTS rispetto all'ultima discontinuità nello stream.

A partire dalla versione 1.2.0 di HLS.js, entrambi i giocatori consigliati passano ID3 tramite CMAF all'utente come se si trattasse di tag ID3. Per questo motivo, gli esempi che seguono sono uguali a quelli per gli stream MPEG2TS HLS. Tuttavia, vale a dire con tutti i giocatori, quindi implementando il supporto per HLS CMAF i flussi di dati potrebbero richiedere un codice univoco per analizzare ID3 tramite eMSG.

Riproduzione in Safari

Safari tratta i metadati ID3 tramite eMSG come pseudo eventi ID3, fornendoli in raggruppa automaticamente i dati come traccia nascosta, in questo modo gli eventi cuechange attivati al momento giusto per elaborare ogni parte dei metadati. Va bene trasferire tutti i metadati all'SDK IMA DAI, indipendentemente dal fatto che siano pertinenti o meno alle tempistiche. Qualsiasi i metadati non correlati all'inserimento di annunci dinamici vengono esclusi 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 ID3 tramite metadati eMSG come pseudo ID3 di eventi, fornendoli in batch, tramite l'evento FRAG_PARSING_METADATA, sotto forma di array di campioni. HLS.js non traduce i dati ID3 da array di byte alle stringhe e non compensa gli eventi nel PTS corrispondente. Non è necessari per decodificare i dati di esempio da array di byte a stringa, poiché l'SDK IMA DAI esegue automaticamente questa 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 con DAI lineari trasmettono i metadati come eventi manifest in uno stream di eventi con il valore personalizzato schemeIdUri urn:google:dai:2018. Ogni evento in questi che contengono un payload di testo e il PTS.

DASH.js

Dash.js fornisce gestori di eventi personalizzati denominati in base al valore logsIdUri di ogni flusso di eventi. Questi gestori personalizzati si attivano in batch, rimanendo l'utente Elaborare il valore PTS per programmare correttamente l'evento. L'SDK IMA DAI può gestire e lo fai 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);
});
...

Suonatore di Shaka

Shaka Player mostra gli eventi come parte del loro evento timelineregionenter. Scadenza a un'incompatibilità di formattazione con Shaka Player, il valore dei metadati deve essere recuperate non elaborate, tramite la proprietà details eventElement.attributes['messageData'].value.

Ecco un esempio:

player.addEventListener('timelineregionenter', function(event) {
  const detail = event.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;
    streamManager.processMetadata("urn:google:dai:2018", mediaId, pts);
  }
});
...

Gestione dei pod

Per la pubblicazione dei pod, esistono diverse configurazioni per il trasferimento a tempo in base ai seguenti criteri:

Tipo di stream dal vivo o VOD
Formato dello stream HLS o DASH
Il tipo di player utilizzato
Il tipo di backend DAI utilizzato

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