Analytics

ExoPlayer 支持各种播放分析需求。归根结底,分析就是收集、解读、汇总和汇总来自回放的数据。这些数据可以在设备上使用(例如,用于日志记录、调试或指导未来的播放决策),也可以报告给服务器以监控所有设备上的播放情况。

分析系统通常需要先收集事件,然后再进一步处理事件,使其变得有意义:

  • 事件收集:可以通过在 ExoPlayer 实例上注册 AnalyticsListener 来实现。已注册的分析监听器会在使用播放器期间收到所发生的事件。每个事件都与播放列表中对应的媒体项以及播放位置和时间戳元数据相关联。
  • 事件处理:某些分析系统会将原始事件上传到服务器,所有事件处理均在服务器端执行。你也可以在设备上处理事件,这样做可能会更简单,或者可以减少需要上传的信息量。ExoPlayer 提供了 PlaybackStatsListener,可让您执行以下处理步骤:
    1. 事件解读:为了便于分析,需要在单次播放的上下文中解读事件。例如,播放器状态更改为 STATE_BUFFERING 的原始事件可能对应于初始缓冲、重新缓冲,或是在跳转后发生的缓冲。
    2. 状态跟踪:此步骤会将事件转换为计数器。例如,可以将状态变化事件转换为计数器,以跟踪每种播放状态下的时长。结果是单次播放的一组基本的分析数据值。
    3. 聚合:此步骤将多次播放的分析数据组合在一起,通常是通过加数计数器来实现的。
    4. 汇总指标的计算:许多最有用的指标都是计算平均值或以其他方式组合基本分析数据值的指标。您可以针对单次或多次播放计算摘要指标。

使用 AnalyticsListener 收集事件

来自播放器的原始播放事件会报告给 AnalyticsListener 实现。您可以轻松添加自己的监听器,并仅替换您感兴趣的方法:

Kotlin

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

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

Java

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

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

传递给每个回调的 EventTime 会将事件与播放列表中的媒体项以及播放位置和时间戳元数据相关联:

  • realtimeMs:事件的挂钟时间。
  • timelinewindowIndexmediaPeriodId:定义播放列表以及播放列表中的内容所属的事件。mediaPeriodId 包含可选的附加信息,例如,指明事件是否属于相应项内的广告。
  • eventPlaybackPositionMs:事件发生时项中的播放位置。
  • currentTimelinecurrentWindowIndexcurrentMediaPeriodIdcurrentPlaybackPositionMs:同上,但针对当前正在播放的项。当前播放的项可能与事件所属的项不同,例如,如果该事件对应于要播放的下一个项的预先缓冲。

使用 PlaybackStatsListener 处理事件

PlaybackStatsListener 是实现设备端事件处理的 AnalyticsListener。它会计算 PlaybackStats,并提供计数器和派生指标,其中包括:

  • 摘要指标,例如总播放时间。
  • 自适应播放质量指标,例如平均视频分辨率。
  • 渲染质量指标,例如丢帧率。
  • 资源使用情况指标,例如通过网络读取的字节数。

您可以在 PlaybackStats Javadoc 中找到可用计数和派生指标的完整列表。

PlaybackStatsListener 会为播放列表中的每个媒体项以及在这些项中插入的每个客户端广告计算单独的 PlaybackStats。您可以提供对 PlaybackStatsListener 的回调,以获取有关播放已完成的通知,并使用传递给该回调的 EventTime 来标识已经完成的播放。您可以汇总多次播放的分析数据。您也可以随时使用 PlaybackStatsListener.getPlaybackStats() 查询当前播放会话的 PlaybackStats

Kotlin

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

Java

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

PlaybackStatsListener 的构造函数提供了保留已处理事件的完整历史记录的选项。请注意,这可能会产生未知的内存开销,具体取决于播放时长和事件数量。因此,仅当您需要访问已处理事件的完整历史记录(而不仅仅是最终分析数据)时,才应开启该功能。

请注意,PlaybackStats 使用一组扩展的状态来不仅指示媒体的状态,还指示用户播放的意图以及更多详细信息,例如播放中断或结束的原因:

播放状态 用户意图玩游戏 无游戏意向
播放前 JOINING_FOREGROUND NOT_STARTEDJOINING_BACKGROUND
正在播放 PLAYING
播放中断 BUFFERINGSEEKING PAUSEDPAUSED_BUFFERINGSUPPRESSEDSUPPRESSED_BUFFERINGINTERRUPTED_BY_AD
结束状态 ENDEDSTOPPEDFAILEDABANDONED

用户想要播放的意图非常重要,有助于区分用户主动等待播放的时间与被动等待时间。例如,PlaybackStats.getTotalWaitTimeMs 会返回在 JOINING_FOREGROUNDBUFFERINGSEEKING 状态下所用的总时间,但不会返回暂停播放的时间。同样,PlaybackStats.getTotalPlayAndWaitTimeMs 将返回用户有意玩游戏的总时间,即总活跃等待时间和在 PLAYING 状态下花费的总时间。

已处理和解读的事件

您可以将 PlaybackStatsListenerkeepHistory=true 结合使用来记录已处理和解释的事件。生成的 PlaybackStats 将包含以下事件列表:

  • playbackStateHistory:扩展播放状态的有序列表,其中包含开始应用这些状态的 EventTime。您还可以使用 PlaybackStats.getPlaybackStateAtTime 查询给定挂钟时间的状态。
  • mediaTimeHistory:挂钟时间和媒体时间对历史记录,可让您重建当时播放的媒体部分。您还可以使用 PlaybackStats.getMediaTimeMsAtRealtimeMs 查询给定挂钟时间的播放位置。
  • videoFormatHistoryaudioFormatHistory:通过 EventTime(开始播放时)播放时使用的视频和音频格式的有序列表。
  • fatalErrorHistorynonFatalErrorHistory:严重和非严重错误的有序列表,其中包含发生这些错误的 EventTime。严重错误是指已结束播放的错误,而非严重错误可能是可以恢复的。

单次播放分析数据

如果您使用 PlaybackStatsListener,即使设置了 keepHistory=false,系统也会自动收集这些数据。最终值是公开字段(可在 PlaybackStats Javadoc 中找到),以及 getPlaybackStateDurationMs 返回的播放状态时长。为方便起见,您还可以使用 getTotalPlayTimeMsgetTotalWaitTimeMs 等方法返回特定播放状态组合的时长。

Kotlin

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

Java

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

汇总多次播放的分析数据

您可以通过调用 PlaybackStats.merge 将多个 PlaybackStats 组合在一起。生成的 PlaybackStats 将包含所有合并播放的汇总数据。请注意,它不包含单个播放事件的历史记录,因为这些事件无法汇总。

PlaybackStatsListener.getCombinedPlaybackStats 可用于获取 PlaybackStatsListener 的生命周期内收集的所有分析数据的汇总视图。

计算摘要指标

除了基本分析数据之外,PlaybackStats 还提供了许多方法来计算摘要指标。

Kotlin

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

Java

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

高级主题

将分析数据与播放元数据相关联

在收集单次播放的分析数据时,您可能希望将播放分析数据与有关正在播放的媒体的元数据相关联。

建议使用 MediaItem.Builder.setTag 设置媒体专用元数据。媒体代码是针对原始事件和 PlaybackStats 完成时报告的 EventTime 的一部分,因此可在处理相应的分析数据时轻松检索:

Kotlin

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

Java

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

报告自定义分析事件

如果您需要向分析数据添加自定义事件,则需要将这些事件保存在您自己的数据结构中,并稍后将其与报告的 PlaybackStats 合并。如果有帮助,您可以扩展 DefaultAnalyticsCollector,以便能够为自定义事件生成 EventTime 实例,并将这些实例发送到已注册的监听器,如以下示例所示。

Kotlin

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()

Java

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