Halaman ini diterjemahkan oleh Cloud Translation API.

Analytics

ExoPlayer mendukung berbagai kebutuhan analisis pemutaran. Pada akhirnya, analisis adalah tentang mengumpulkan, menafsirkan, menggabungkan, dan meringkas data dari pemutaran. Data ini dapat digunakan di perangkat—misalnya untuk logging, proses debug, atau untuk menginformasikan keputusan pemutaran di masa mendatang—atau dilaporkan ke server untuk memantau pemutaran di semua perangkat.

Sistem analisis biasanya perlu mengumpulkan peristiwa terlebih dahulu, lalu memprosesnya lebih lanjut agar peristiwa tersebut bermakna:

Pengumpulan peristiwa: Tindakan ini dapat dilakukan dengan mendaftarkan AnalyticsListener di instance ExoPlayer. Pemroses analisis terdaftar menerima peristiwa saat terjadi selama penggunaan pemutar. Setiap peristiwa dikaitkan dengan item media yang sesuai dalam playlist, serta metadata stempel waktu dan posisi pemutaran.
Pemrosesan peristiwa: Beberapa sistem analisis mengupload peristiwa mentah ke server, dengan semua pemrosesan peristiwa dilakukan di sisi server. Anda juga dapat memproses peristiwa di perangkat, dan melakukannya mungkin lebih sederhana atau mengurangi jumlah informasi yang perlu diupload. ExoPlayer menyediakan PlaybackStatsListener, yang memungkinkan Anda melakukan langkah-langkah pemrosesan berikut:
1. Interpretasi peristiwa: Agar berguna untuk tujuan analisis, peristiwa harus diinterpretasikan dalam konteks satu pemutaran. Misalnya, peristiwa mentah perubahan status pemutar menjadi STATE_BUFFERING dapat sesuai dengan buffering awal, buffering ulang, atau buffering yang terjadi setelah pencarian.
2. Pelacakan status: Langkah ini mengonversi peristiwa menjadi penghitung. Misalnya, peristiwa perubahan status dapat dikonversi menjadi penghitung yang melacak jumlah waktu yang dihabiskan di setiap status pemutaran. Hasilnya adalah kumpulan dasar nilai data analisis untuk satu pemutaran.
3. Agregasi: Langkah ini menggabungkan data analisis di beberapa pemutaran, biasanya dengan menambahkan penghitung.
4. Penghitungan metrik ringkasan: Banyak metrik yang paling berguna adalah metrik yang menghitung rata-rata atau menggabungkan nilai data analisis dasar dengan cara lain. Metrik ringkasan dapat dihitung untuk satu atau beberapa pemutaran.

Pengumpulan peristiwa dengan AnalyticsListener

Peristiwa pemutaran mentah dari pemutar dilaporkan ke implementasi AnalyticsListener. Anda dapat dengan mudah menambahkan pemroses Anda sendiri dan mengganti metode yang Anda minati saja:

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 yang diteruskan ke setiap callback mengaitkan peristiwa ke item media dalam playlist, serta metadata stempel waktu dan posisi pemutaran:

realtimeMs: Waktu jam dinding peristiwa.
timeline, windowIndex, dan mediaPeriodId: Menentukan playlist dan item dalam playlist tempat peristiwa berada. mediaPeriodId berisi informasi tambahan opsional, misalnya menunjukkan apakah peristiwa termasuk dalam iklan dalam item.
eventPlaybackPositionMs: Posisi pemutaran dalam item saat peristiwa terjadi.
currentTimeline, currentWindowIndex, currentMediaPeriodId, dan currentPlaybackPositionMs: Seperti di atas, tetapi untuk item yang sedang diputar. Item yang sedang diputar mungkin berbeda dengan item tempat peristiwa tersebut berada, misalnya jika peristiwa sesuai dengan pra-buffering item berikut yang akan diputar.

Pemrosesan peristiwa dengan PlaybackStatsListener

PlaybackStatsListener adalah AnalyticsListener yang mengimplementasikan pemrosesan peristiwa di perangkat. Fungsi ini menghitung PlaybackStats, dengan penghitung dan metrik turunan termasuk:

Metrik ringkasan, misalnya total waktu pemutaran.
Metrik kualitas pemutaran adaptif, misalnya resolusi video rata-rata.
Metrik kualitas rendering, misalnya kecepatan frame yang dihapus.
Metrik penggunaan resource, misalnya jumlah byte yang dibaca melalui jaringan.

Anda akan menemukan daftar lengkap jumlah yang tersedia dan metrik turunan di PlaybackStats Javadoc.

PlaybackStatsListener menghitung PlaybackStats terpisah untuk setiap item media dalam playlist, dan juga setiap iklan sisi klien yang disisipkan dalam item ini. Anda dapat memberikan callback ke PlaybackStatsListener untuk mendapatkan informasi tentang pemutaran yang selesai, dan menggunakan EventTime yang diteruskan ke callback untuk mengidentifikasi pemutaran mana yang selesai. Anda dapat menggabungkan data analisis untuk beberapa pemutaran. Anda juga dapat membuat kueri PlaybackStats untuk sesi pemutaran saat ini kapan saja menggunakan PlaybackStatsListener.getPlaybackStats().

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

Konstruktor PlaybackStatsListener memberikan opsi untuk menyimpan histori lengkap peristiwa yang diproses. Perhatikan bahwa hal ini dapat menimbulkan overhead memori yang tidak diketahui bergantung pada durasi pemutaran dan jumlah peristiwa. Oleh karena itu, sebaiknya aktifkan hanya jika Anda memerlukan akses ke histori lengkap peristiwa yang diproses, bukan hanya ke data analisis akhir.

Perhatikan bahwa PlaybackStats menggunakan kumpulan status yang diperluas untuk menunjukkan tidak hanya status media, tetapi juga niat pengguna untuk memutar dan informasi yang lebih mendetail seperti alasan pemutaran terganggu atau berakhir:

Status pemutaran	Niat pengguna untuk bermain	Tidak ada niat untuk bermain
Sebelum pemutaran	`JOINING_FOREGROUND`	`NOT_STARTED`, `JOINING_BACKGROUND`
Pemutaran aktif	`PLAYING`
Pemutaran terganggu	`BUFFERING`, `SEEKING`	`PAUSED`, `PAUSED_BUFFERING`, `SUPPRESSED`, `SUPPRESSED_BUFFERING`, `INTERRUPTED_BY_AD`
Status akhir		`ENDED`, `STOPPED`, `FAILED`, `ABANDONED`

Niat pengguna untuk memutar iklan penting untuk membedakan waktu saat pengguna secara aktif menunggu pemutaran dilanjutkan dari waktu tunggu pasif. Misalnya, PlaybackStats.getTotalWaitTimeMs menampilkan total waktu yang dihabiskan dalam status JOINING_FOREGROUND, BUFFERING, dan SEEKING, tetapi bukan waktu saat pemutaran dijeda. Demikian pula, PlaybackStats.getTotalPlayAndWaitTimeMs akan menampilkan total waktu dengan niat pengguna untuk bermain, yaitu total waktu tunggu aktif dan total waktu yang dihabiskan dalam status PLAYING.

Peristiwa yang diproses dan ditafsirkan

Anda dapat merekam peristiwa yang diproses dan ditafsirkan menggunakan PlaybackStatsListener dengan keepHistory=true. PlaybackStats yang dihasilkan akan berisi daftar peristiwa berikut:

playbackStateHistory: Daftar yang diurutkan dari status pemutaran yang diperpanjang dengan EventTime tempat status tersebut mulai diterapkan. Anda juga dapat menggunakan PlaybackStats.getPlaybackStateAtTime untuk mencari status pada waktu jam dinding tertentu.
mediaTimeHistory: Histori waktu jam dinding dan pasangan waktu media yang memungkinkan Anda merekonstruksi bagian media yang sedang diputar pada saat itu. Anda juga dapat menggunakan PlaybackStats.getMediaTimeMsAtRealtimeMs untuk mencari posisi pemutaran pada waktu jam dinding tertentu.
videoFormatHistory dan audioFormatHistory: Daftar urut format video dan audio yang digunakan selama pemutaran dengan EventTime tempat format tersebut mulai digunakan.
fatalErrorHistory dan nonFatalErrorHistory: Daftar error fatal dan non-fatal yang diurutkan dengan EventTime tempat error tersebut terjadi. Error fatal adalah error yang menghentikan pemutaran, sedangkan error non-fatal mungkin dapat dipulihkan.

Data analisis pemutaran tunggal

Data ini otomatis dikumpulkan jika Anda menggunakan PlaybackStatsListener, meskipun dengan keepHistory=false. Nilai akhir adalah kolom publik yang dapat Anda temukan di PlaybackStats Javadoc dan durasi status pemutaran yang ditampilkan oleh getPlaybackStateDurationMs. Untuk memudahkan, Anda juga akan menemukan metode seperti getTotalPlayTimeMs dan getTotalWaitTimeMs yang menampilkan durasi kombinasi status pemutaran tertentu.

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

Menggabungkan data analisis dari beberapa pemutaran

Anda dapat menggabungkan beberapa PlaybackStats sekaligus dengan memanggil PlaybackStats.merge. PlaybackStats yang dihasilkan akan berisi data agregat dari semua pemutaran yang digabungkan. Perhatikan bahwa laporan ini tidak akan berisi histori setiap peristiwa pemutaran, karena peristiwa tersebut tidak dapat digabungkan.

PlaybackStatsListener.getCombinedPlaybackStats dapat digunakan untuk mendapatkan tampilan gabungan dari semua data analisis yang dikumpulkan selama masa aktif PlaybackStatsListener.

Metrik ringkasan yang dihitung

Selain data analisis dasar, PlaybackStats menyediakan banyak metode untuk menghitung metrik ringkasan.

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

Topik lanjutan

Mengaitkan data analisis dengan metadata pemutaran

Saat mengumpulkan data analisis untuk setiap pemutaran, Anda dapat mengaitkan data analisis pemutaran dengan metadata tentang media yang diputar.

Sebaiknya tetapkan metadata khusus media dengan MediaItem.Builder.setTag. Tag media adalah bagian dari EventTime yang dilaporkan untuk peristiwa mentah dan saat PlaybackStats selesai, sehingga dapat diambil dengan mudah saat menangani data analisis yang sesuai:

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

Melaporkan peristiwa analisis kustom

Jika perlu menambahkan peristiwa kustom ke data analisis, Anda harus menyimpan peristiwa ini dalam struktur data Anda sendiri dan menggabungkannya dengan PlaybackStats yang dilaporkan nanti. Jika membantu, Anda dapat memperluas DefaultAnalyticsCollector agar dapat membuat instance EventTime untuk peristiwa kustom dan mengirimnya ke pemroses yang sudah terdaftar seperti yang ditunjukkan dalam contoh berikut.

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