Cette page a été traduite par l'API Cloud Translation.

Gérer les métadonnées planifiées dans les flux linéaires d'insertion dynamique d'annonce

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é de TXXX avec une chaîne associée commençant par google_.

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é. Elle utilise les arguments suivants:

type: chaîne contenant le type d'événement en cours de traitement. Acceptées les valeurs sont ID3 pour HLS ou urn:google:dai:2018 pour DASH.
data: soit une valeur de chaîne précédée de google_, soit un tableau d'octets qui suit ce format ID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxx
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 le décodage et le 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 CMAF à l'utilisateur comme s'il s'agissait de tags ID3. Pour cette raison, 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 urn:google:dai:2018 de schemeIdUri. 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 sont déclenchés 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 dans 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);
       }
}