Le SDK IMA (Interactive Media Ads) pour l'insertion dynamique d'annonce les informations sur les métadonnées intégrées aux segments multimédias du flux (métadonnées au sein du groupe) ; ou dans le fichier manifeste de streaming (métadonnées du fichier manifeste) pour suivre l'activité des spectateurs et les événements d'annonce côté client. Les métadonnées sont envoyées dans différents formats, selon le type de diffusion en cours de lecture.
Le lecteur vidéo reçoit des métadonnées minutées par lot. Selon le joueur, les métadonnées peuvent être affichées à l'heure planifiée ou par lots. Chaque métadonnée est associée à un code temporel de présentation (PTS) déclenchée.
Votre application est responsable de la capture des métadonnées et de leur transfert vers le SDK IMA DAI. Le SDK propose les méthodes suivantes pour transmettre ces informations:
- onTimedMetadata
Cette méthode transmet les chaînes de métadonnées prêtes à être traitées au SDK. Il n'a qu'un seul argument:
metadata: objet contenant une clé deTXXXavec une chaîne associée commençant pargoogle_.
- processMetadata
Cette méthode planifie le traitement des chaînes de métadonnées par le SDK après l'événement PTS spécifié. Il utilise les arguments suivants:
type: chaîne contenant le type d'événement en cours de traitement. Acceptées les valeurs sontID3pour HLS ouurn:google:dai:2018pour DASH.data: soit une valeur de chaîne précédée degoogle_, soit un tableau d'octets qui décode en une telle chaîne.timestamp: code temporel (en secondes) du traitement des données.
Chaque type de flux compatible avec le SDK IMA DAI utilise un format unique des métadonnées, comme décrit dans les sections suivantes.
Flux HLS MPEG2TS
Les flux HLS linéaires pour l'insertion dynamique d'annonces utilisant les segments MPEG2TS transmettent des métadonnées synchronisées au par le biais de tags ID3 intra-bande. Ces tags ID3 sont intégrés dans la MPEG2TS et reçoivent le nom de champ TXXX (pour un texte personnalisé défini par l'utilisateur contenu).
Lecture dans Safari
Safari traite automatiquement les balises ID3 en tant que piste cachée, c'est-à-dire les événements cuechange. se déclencher au bon moment pour traiter chaque élément de métadonnées. Vous pouvez passer toutes les métadonnées au SDK IMA DAI, quel que soit leur contenu ou leur type. Non pertinent les métadonnées sont automatiquement filtrées.
Exemple :
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 fournit des balises ID3 par lots via l'événement FRAG_PARSING_METADATA,
sous forme de tableau d'échantillons. HLS.js ne traduit pas les données ID3 des tableaux d'octets
aux chaînes et ne décale pas les
événements vers leur PTS correspondant. Ce n'est pas le cas
nécessaires pour décoder les échantillons de données du tableau d'octets en chaîne, ou pour filtrer
des balises ID3 non pertinentes, car le SDK IMA DAI effectue ce décodage et ce filtrage
automatiquement.
Exemple :
hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
if (streamManager && data) {
data.samples.forEach((sample) => {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
});
...
Flux CMAF du HLS
Flux HLS linéaires pour l'insertion dynamique d'annonces à l'aide de la carte CMAF (Common Media Application Framework) de métadonnées minutées à l'aide de boîtes eMSGv1 intégrées à la bande après les étapes ID3 à la norme CMAF. Ces boîtes eMSG sont intégré au début de chaque segment multimédia, chaque eMSG ID3 contenant un PTS relatif à la dernière discontinuité du flux.
Depuis la version 1.2.0 de HLS.js, nos deux lecteurs suggérés transmettent le code ID3. via le CMAF à l'utilisateur comme s'il s'agissait de tags ID3. Pour cette raison, le Les exemples suivants sont les mêmes que pour les flux HLS MPEG2TS. Toutefois, cela peut ne s'applique pas à tous les joueurs. La prise en charge du CMAF HLS les flux peuvent nécessiter un code unique pour analyser les ID3 via eMSG.
Lecture dans Safari
Safari traite les métadonnées ID3 via eMSG comme des événements pseudo-ID3 et les fournit dans automatiquement sous forme de piste cachée, de sorte que les événements cuechange soient déclenché au bon moment pour traiter chaque élément de métadonnées. C’est bien transmettre toutes les métadonnées au SDK IMA DAI, qu'elles soient pertinentes ou non au niveau du calendrier. N'importe quelle valeur les métadonnées non liées à l'insertion dynamique d'annonces sont automatiquement filtrées.
Exemple :
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
Depuis la version 1.2.0, HLS.js traite les métadonnées ID3 via eMSG comme un pseudo-ID3.
en les fournissant de manière groupée via l'événement FRAG_PARSING_METADATA,
sous forme de tableau d'échantillons. HLS.js ne traduit pas les données ID3 des tableaux d'octets.
aux chaînes et ne décale pas les événements vers le PTS correspondant. Ce n'est pas le cas
décoder les échantillons de données du tableau d'octets en chaîne, car le SDK IMA DAI effectue automatiquement ce décodage.
Exemple :
hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
if (streamManager && data) {
data.samples.forEach((sample) => {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
});
...
Flux DASH
Les flux DASH linéaires pour l'insertion dynamique d'annonces transmettent des métadonnées en tant qu'événements de fichier manifeste dans un flux d'événements avec
la valeur personnalisée schemeIdUri urn:google:dai:2018. Chaque événement de ces
les flux contient une charge utile
de texte et le PTS.
DASH.js
Dash.js fournit des gestionnaires d'événements personnalisés nommés d'après la valeur schemaIdUri de chaque
flux d'événements. Ces gestionnaires personnalisés se déclenchent par lots. C'est à vous de décider
traiter la valeur PTS pour synchroniser correctement l'événement. Le SDK IMA DAI peut gérer
à l'aide de la méthode streamManager processMetadata().
Exemple :
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);
});
...
Lecteur Shaka
Shaka Player présente des événements dans son événement timelineregionenter. Date limite
en cas d'incompatibilité de format avec Shaka Player, la valeur de métadonnées doit être
récupérées brutes, à l'aide de la propriété "detail"
eventElement.attributes['messageData'].value
Exemple :
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);
}
});
...
Diffusion de séries d'annonces
Pour la diffusion de pods, il existe différentes configurations permettant de transmettre métadonnées en fonction des critères suivants:
- Type de flux en direct ou VOD
- Format de flux HLS ou DASH
- Type de lecteur utilisé
- Type de backend d'insertion dynamique d'annonce utilisé
Format de flux HLS (flux en direct et à la demande, lecteur HLS.js)
Si vous utilisez un lecteur HLS.js, écoutez
l'événement HLS.js FRAG_PARSING_METADATA pour obtenir les métadonnées ID3 et les transmettre au
SDK avec StreamManager.processMetadata().
Pour lire automatiquement la vidéo une fois que tout est chargé et prêt, écoutez
l'événement MANIFEST_PARSED HLS.js pour déclencher la lecture ;
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 (format de flux DASH, type de flux en direct et vidéo à la demande)
Si vous utilisez un lecteur DASH.js, vous devez utiliser des chaînes différentes pour écouter les métadonnées ID3 pour le direct ou la vidéo à la demande. flux:
- Diffusions en direct:
'https://developer.apple.com/streaming/emsg-id3' - Flux de vidéo à la demande:
'urn:google:dai:2018'
Transmettez les métadonnées ID3 au SDK avec StreamManager.processMetadata().
Pour afficher automatiquement les commandes vidéo une fois que tout est chargé et prêt,
écouter l'événement 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);
}
Lecteur Shaka avec diffusions en direct (format de flux DASH)
Si vous utilisez le lecteur Shaka pour
diffusion en direct, utilisez la chaîne 'emsg' pour écouter les événements de métadonnées.
Utilisez ensuite les données du message d'événement de votre appel à 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});
}
Lecteur Shaka avec flux de vidéo à la demande (format de flux DASH)
Si vous utilisez le lecteur Shaka pour
la lecture d'un flux VOD. Utilisez la chaîne 'timelineregionenter' pour l'écouter ;
des événements de métadonnées. Utilisez ensuite les données du message d'événement de votre appel pour
StreamManager.processMetadata()
avec la chaîne '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);
}
}