Analytics

ExoPlayer est compatible avec un large éventail de besoins en analyse de la lecture. En fin de compte, l'analyse consiste à collecter, interpréter, agréger et résumer les données des lectures. Ces données peuvent être utilisées sur l'appareil (par exemple, pour la journalisation, le débogage ou pour éclairer les futures décisions de lecture) ou transmises à un serveur pour surveiller les lectures sur tous les appareils.

Un système d'analyse doit généralement commencer par collecter des événements, puis les traiter pour les rendre pertinents:

• Collecte des événements : pour ce faire, enregistrez un AnalyticsListener sur une instance ExoPlayer. Les écouteurs d'analyse enregistrés reçoivent les événements au fur et à mesure de leur utilisation du lecteur. Chaque événement est associé à l'élément multimédia correspondant dans la playlist, ainsi qu'aux métadonnées de position de lecture et d'horodatage.
• Traitement des événements : certains systèmes d'analyse importent des événements bruts sur un serveur, et tout le traitement des événements est effectué côté serveur. Il est également possible de traiter les événements sur l'appareil. Cela peut être plus simple ou réduire la quantité d'informations à importer. ExoPlayer fournit PlaybackStatsListener, qui vous permet d'effectuer les étapes de traitement suivantes :
  1. Interprétation des événements: pour être utiles à des fins d'analyse, les événements doivent être interprétés dans le contexte d'une seule lecture. Par exemple, l'événement brut d'un changement d'état du lecteur vers STATE_BUFFERING peut correspondre à une mise en tampon initiale, à une remise en tampon ou à une mise en tampon qui se produit après une recherche.
  2. Suivi de l'état: cette étape convertit les événements en compteurs. Par exemple, les événements de changement d'état peuvent être convertis en compteurs qui suivent le temps passé dans chaque état de lecture. Le résultat est un ensemble de valeurs de données analytiques de base pour une seule lecture.
  3. Agrégation: cette étape combine les données analytiques de plusieurs lectures, généralement en additionnant les compteurs.
  4. Calcul des métriques récapitulatives: de nombreuses métriques parmi les plus utiles sont celles qui calculent des moyennes ou combinent les valeurs de données analytiques de base de différentes manières. Les métriques récapitulatives peuvent être calculées pour une ou plusieurs lectures.

Collecte d'événements avec AnalyticsListener

Les événements de lecture bruts du lecteur sont signalés aux implémentations AnalyticsListener. Vous pouvez facilement ajouter votre propre écouteur et ne remplacer que les méthodes qui vous intéressent:

exoPlayer.addAnalyticsListener(
  object : AnalyticsListener {
    override fun onPlaybackStateChanged(
      eventTime: EventTime, @Player.State state: Int
    ) {}

    override fun onDroppedVideoFrames(
      eventTime: EventTime,
      droppedFrames: Int,
      elapsedMs: Long,
    ) {}
  }
)

exoPlayer.addAnalyticsListener(
    new AnalyticsListener() {
      @Override
      public void onPlaybackStateChanged(
          EventTime eventTime, @Player.State int state) {}

      @Override
      public void onDroppedVideoFrames(
          EventTime eventTime, int droppedFrames, long elapsedMs) {}
    });

Le EventTime transmis à chaque rappel associe l'événement à un élément multimédia de la playlist, ainsi qu'aux métadonnées de position de lecture et d'horodatage:

• realtimeMs: heure de l'événement.
• timeline, windowIndex et mediaPeriodId: définit la playlist et l'élément de la playlist à laquelle appartient l'événement. mediaPeriodId contient des informations facultatives supplémentaires, indiquant par exemple si l'événement appartient à une annonce au sein de l'élément.
• eventPlaybackPositionMs: position de lecture de l'élément lorsque l'événement s'est produit.
• currentTimeline, currentWindowIndex, currentMediaPeriodId et currentPlaybackPositionMs: comme ci-dessus, mais pour l'élément en cours de lecture. L'élément en cours de lecture peut être différent de l'élément auquel l'événement appartient, par exemple si l'événement correspond à la prémise en mémoire tampon de l'élément suivant à lire.

Traitement des événements avec PlaybackStatsListener

PlaybackStatsListener est un AnalyticsListener qui implémente le traitement des événements sur l'appareil. Il calcule PlaybackStats, avec des compteurs et des métriques dérivées, y compris:

• Métriques récapitulatives, comme la durée totale de lecture.
• Métriques de qualité de lecture adaptative, comme la résolution vidéo moyenne
• Métriques de qualité du rendu, par exemple le taux de perte de frames.
• Métriques d'utilisation des ressources, comme le nombre d'octets lus sur le réseau.

Vous trouverez la liste complète des décomptes disponibles et des métriques dérivées dans le Javadoc PlaybackStats.

PlaybackStatsListener calcule des PlaybackStats distincts pour chaque élément multimédia de la playlist, ainsi que pour chaque annonce côté client insérée dans ces éléments. Vous pouvez fournir un rappel à PlaybackStatsListener pour être informé des lectures terminées et utiliser le EventTime transmis au rappel pour identifier la lecture terminée. Vous pouvez agréger les données analytiques pour plusieurs lectures. Il est également possible d'interroger PlaybackStats pour la session de lecture en cours à tout moment à l'aide de PlaybackStatsListener.getPlaybackStats().

exoPlayer.addAnalyticsListener(
  PlaybackStatsListener(/* keepHistory= */ true) {
    eventTime: EventTime?,
    playbackStats: PlaybackStats?,
    -> // Analytics data for the session started at `eventTime` is ready.
  }
)

exoPlayer.addAnalyticsListener(
    new PlaybackStatsListener(
        /* keepHistory= */ true,
        (eventTime, playbackStats) -> {
          // Analytics data for the session started at `eventTime` is ready.
        }));

Le constructeur de PlaybackStatsListener permet de conserver l'historique complet des événements traités. Notez que cela peut entraîner des frais généraux de mémoire inconnus en fonction de la durée de la lecture et du nombre d'événements. Par conséquent, vous ne devez l'activer que si vous avez besoin d'accéder à l'historique complet des événements traités, et non uniquement aux données analytiques finales.

Notez que PlaybackStats utilise un ensemble étendu d'états pour indiquer non seulement l'état du contenu multimédia, mais aussi l'intention de l'utilisateur de le lire et des informations plus détaillées, telles que la raison pour laquelle la lecture a été interrompue ou terminée:

L'intention de l'utilisateur de lire est importante pour distinguer les moments où l'utilisateur attendait activement la poursuite de la lecture des temps d'attente passifs. Par exemple, PlaybackStats.getTotalWaitTimeMs renvoie la durée totale passée dans les états JOINING_FOREGROUND, BUFFERING et SEEKING, mais pas l'heure à laquelle la lecture a été mise en pause. De même, PlaybackStats.getTotalPlayAndWaitTimeMs renvoie la durée totale avec l'intention de l'utilisateur de jouer, c'est-à-dire la durée d'attente active totale et la durée totale passée dans l'état PLAYING.

Événements traités et interprétés

Vous pouvez enregistrer des événements traités et interprétés en utilisant PlaybackStatsListener avec keepHistory=true. Le PlaybackStats obtenu contient les listes d'événements suivantes:

• playbackStateHistory: liste ordonnée des états de lecture étendue avec le EventTime à partir duquel ils ont commencé à s'appliquer. Vous pouvez également utiliser PlaybackStats.getPlaybackStateAtTime pour rechercher l'état à un moment donné.
• mediaTimeHistory: historique des paires d'heures réelles et d'heures multimédias, qui vous permet de reconstruire les parties du contenu multimédia diffusées à un moment donné. Vous pouvez également utiliser PlaybackStats.getMediaTimeMsAtRealtimeMs pour rechercher la position de lecture à une heure donnée.
• videoFormatHistory et audioFormatHistory: listes triées des formats vidéo et audio utilisés pendant la lecture, avec le EventTime à partir duquel ils ont commencé à être utilisés.
• fatalErrorHistory et nonFatalErrorHistory: listes triées d'erreurs fatales et non fatales, avec l'ID EventTime où elles se sont produites. Les erreurs fatales sont celles qui ont mis fin à la lecture, tandis que les erreurs non fatales peuvent avoir été récupérables.

Données analytiques sur une seule lecture

Ces données sont collectées automatiquement si vous utilisez PlaybackStatsListener, même avec keepHistory=false. Les valeurs finales sont les champs publics que vous pouvez trouver dans la documentation Javadoc PlaybackStats et les durées d'état de lecture renvoyées par getPlaybackStateDurationMs. Pour plus de commodité, vous trouverez également des méthodes telles que getTotalPlayTimeMs et getTotalWaitTimeMs qui renvoient la durée de combinaisons d'états de lecture spécifiques.

Log.d(
  "DEBUG",
  "Playback summary: " +
    "play time = " +
    playbackStats.totalPlayTimeMs +
    ", rebuffers = " +
    playbackStats.totalRebufferCount
)

Log.d(
    "DEBUG",
    "Playback summary: "
        + "play time = "
        + playbackStats.getTotalPlayTimeMs()
        + ", rebuffers = "
        + playbackStats.totalRebufferCount);

Agrégation des données analytiques de plusieurs lectures

Vous pouvez combiner plusieurs PlaybackStats en appelant PlaybackStats.merge. Le PlaybackStats obtenu contiendra les données globales de toutes les lectures fusionnées. Notez qu'il ne contient pas l'historique des événements de lecture individuels, car ils ne peuvent pas être agrégés.

PlaybackStatsListener.getCombinedPlaybackStats permet d'obtenir une vue agrégée de toutes les données d'analyse collectées au cours de la durée de vie d'une PlaybackStatsListener.

Métriques récapitulatives calculées

En plus des données analytiques de base, PlaybackStats fournit de nombreuses méthodes pour calculer des métriques récapitulatives.

Log.d(
  "DEBUG",
  "Additional calculated summary metrics: " +
    "average video bitrate = " +
    playbackStats.meanVideoFormatBitrate +
    ", mean time between rebuffers = " +
    playbackStats.meanTimeBetweenRebuffers
)

Log.d(
    "DEBUG",
    "Additional calculated summary metrics: "
        + "average video bitrate = "
        + playbackStats.getMeanVideoFormatBitrate()
        + ", mean time between rebuffers = "
        + playbackStats.getMeanTimeBetweenRebuffers());

Rubriques avancées

Associer des données analytiques aux métadonnées de lecture

Lorsque vous collectez des données analytiques pour des lectures individuelles, vous pouvez associer les données analytiques de lecture aux métadonnées sur le contenu multimédia en cours de lecture.

Il est conseillé de définir des métadonnées spécifiques aux contenus multimédias avec MediaItem.Builder.setTag. Le tag multimédia fait partie du EventTime enregistré pour les événements bruts et une fois les PlaybackStats terminés. Il peut donc être facilement récupéré lors du traitement des données d'analyse correspondantes:

PlaybackStatsListener(/* keepHistory= */ false) {
  eventTime: EventTime,
  playbackStats: PlaybackStats ->
  val mediaTag =
    eventTime.timeline
      .getWindow(eventTime.windowIndex, Timeline.Window())
      .mediaItem
      .localConfiguration
      ?.tag
    // Report playbackStats with mediaTag metadata.
}

new PlaybackStatsListener(
    /* keepHistory= */ false,
    (eventTime, playbackStats) -> {
      Object mediaTag =
          eventTime.timeline.getWindow(eventTime.windowIndex, new Timeline.Window())
              .mediaItem
              .localConfiguration
              .tag;
      // Report playbackStats with mediaTag metadata.
    });

Créer des rapports sur les événements d'analyse personnalisés

Si vous devez ajouter des événements personnalisés aux données analytiques, vous devez les enregistrer dans votre propre structure de données et les combiner avec les PlaybackStats signalées ultérieurement. Si cela vous aide, vous pouvez étendre DefaultAnalyticsCollector pour pouvoir générer des instances EventTime pour vos événements personnalisés et les envoyer aux écouteurs déjà enregistrés, comme illustré dans l'exemple suivant.

private interface ExtendedListener : AnalyticsListener {
  fun onCustomEvent(eventTime: EventTime)
}

private class ExtendedCollector : DefaultAnalyticsCollector(Clock.DEFAULT) {
  fun customEvent() {
    val eventTime = generateCurrentPlayerMediaPeriodEventTime()
    sendEvent(eventTime, CUSTOM_EVENT_ID) { listener: AnalyticsListener ->
      if (listener is ExtendedListener) {
        listener.onCustomEvent(eventTime)
      }
    }
  }
}

// Usage - Setup and listener registration.
val player = ExoPlayer.Builder(context).setAnalyticsCollector(ExtendedCollector()).build()
player.addAnalyticsListener(
  object : ExtendedListener {
    override fun onCustomEvent(eventTime: EventTime?) {
      // Save custom event for analytics data.
    }
  }
)
// Usage - Triggering the custom event.
(player.analyticsCollector as ExtendedCollector).customEvent()

private interface ExtendedListener extends AnalyticsListener {
  void onCustomEvent(EventTime eventTime);
}

private static class ExtendedCollector extends DefaultAnalyticsCollector {
  public ExtendedCollector() {
    super(Clock.DEFAULT);
  }

  public void customEvent() {
    AnalyticsListener.EventTime eventTime = generateCurrentPlayerMediaPeriodEventTime();
    sendEvent(
        eventTime,
        CUSTOM_EVENT_ID,
        listener -> {
          if (listener instanceof ExtendedListener) {
            ((ExtendedListener) listener).onCustomEvent(eventTime);
          }
        });
  }
}

// Usage - Setup and listener registration.
ExoPlayer player =
    new ExoPlayer.Builder(context).setAnalyticsCollector(new ExtendedCollector()).build();
player.addAnalyticsListener(
    (ExtendedListener) eventTime -> {
      // Save custom event for analytics data.
    });
// Usage - Triggering the custom event.
((ExtendedCollector) player.getAnalyticsCollector()).customEvent();