ExoPlayer는 다양한 재생 분석 요구사항을 지원합니다. 궁극적으로 분석은 재생에서 데이터를 수집, 해석, 집계, 요약하는 것입니다. 이 데이터는 기기에서 사용(예: 로깅, 디버깅 또는 향후 재생 결정 알림)하거나 서버에 보고하여 모든 기기의 재생을 모니터링할 수 있습니다.
일반적으로 분석 시스템은 이벤트를 먼저 수집한 후 의미 있는 이벤트를 만들기 위해 추가로 처리해야 합니다.
- 이벤트 수집:
ExoPlayer
인스턴스에AnalyticsListener
를 등록하면 됩니다. 등록된 분석 리스너는 플레이어를 사용하는 동안 발생하는 이벤트를 수신합니다. 각 이벤트는 재생 위치 및 타임스탬프 메타데이터뿐만 아니라 재생목록의 해당 미디어 항목과도 연결됩니다. - 이벤트 처리: 일부 분석 시스템은 원시 이벤트를 서버에 업로드하고 모든 이벤트 처리는 서버 측에서 수행됩니다. 기기에서 이벤트를 처리할 수도 있으며, 이렇게 하면 더 간단하거나 업로드해야 하는 정보의 양을 줄일 수 있습니다. ExoPlayer는 다음 처리 단계를 실행할 수 있는
PlaybackStatsListener
를 제공합니다.- 이벤트 해석: 이벤트를 분석 목적으로 사용하려면 단일 재생이라는 컨텍스트에서 이벤트를 해석해야 합니다. 예를 들어 플레이어 상태가
STATE_BUFFERING
로 변경되는 원시 이벤트는 탐색 이후에 발생하는 초기 버퍼링, 리버퍼링 또는 버퍼링에 상응할 수 있습니다. - 상태 추적: 이 단계는 이벤트를 카운터로 변환합니다. 예를 들어 상태 변경 이벤트는 각 재생 상태에서 소요된 시간을 추적하는 카운터로 변환될 수 있습니다. 그 결과 단일 재생에 대한 기본 분석 데이터 값 집합이 생성됩니다.
- 집계: 이 단계에서는 일반적으로 카운터를 더하여 여러 재생에서 분석 데이터를 결합합니다.
- 요약 측정항목 계산: 가장 유용한 측정항목은 평균을 계산하거나 다른 방식으로 기본 애널리틱스 데이터 값을 결합하는 측정항목입니다. 요약 측정항목은 단일 재생 또는 다중 재생에 관해 계산할 수 있습니다.
- 이벤트 해석: 이벤트를 분석 목적으로 사용하려면 단일 재생이라는 컨텍스트에서 이벤트를 해석해야 합니다. 예를 들어 플레이어 상태가
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
: 이벤트의 벽시계 시간입니다.timeline
,windowIndex
,mediaPeriodId
: 이벤트가 속한 재생목록 내에서 재생목록과 항목을 정의합니다.mediaPeriodId
에는 이벤트가 항목 내 광고에 속하는지 여부를 나타내는 추가 정보(예: 선택사항)가 포함됩니다.eventPlaybackPositionMs
: 이벤트가 발생했을 때 항목의 재생 위치입니다.currentTimeline
,currentWindowIndex
,currentMediaPeriodId
,currentPlaybackPositionMs
: 위와 같지만 현재 재생 중인 항목에 적용됩니다. 현재 재생 중인 항목은 이벤트가 속한 항목과 다를 수 있습니다(예: 이벤트가 재생할 다음 항목의 사전 버퍼링에 해당하는 경우).
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 |
JOINING_BACKGROUND NOT_STARTED |
활성 재생 | PLAYING |
|
재생 중단됨 | SEEKING BUFFERING |
PAUSED , PAUSED_BUFFERING , SUPPRESSED , SUPPRESSED_BUFFERING , INTERRUPTED_BY_AD |
종료 상태 | ENDED , STOPPED , FAILED , ABANDONED |
사용자가 재생을 위해 적극적으로 대기한 시간과 수동적 대기 시간을 구분하려면 사용자의 플레이 의도가 중요합니다. 예를 들어 PlaybackStats.getTotalWaitTimeMs
는 JOINING_FOREGROUND
, BUFFERING
, SEEKING
상태에서 소요된 총 시간을 반환하지만 재생이 일시중지된 시간은 반환하지 않습니다. 마찬가지로 PlaybackStats.getTotalPlayAndWaitTimeMs
는 사용자가 플레이하려는 총 시간, 즉 총 활성 대기 시간과 PLAYING
상태에서 소요된 총 시간을 반환합니다.
처리 및 해석된 이벤트
keepHistory=true
와 함께 PlaybackStatsListener
를 사용하여 처리 및 해석된 이벤트를 기록할 수 있습니다. 결과 PlaybackStats
에는 다음 이벤트 목록이 포함됩니다.
playbackStateHistory
: 적용하기 시작한EventTime
가 있는 확장 재생 상태의 순서가 지정된 목록입니다.PlaybackStats.getPlaybackStateAtTime
를 사용하여 지정된 실제 경과 시간에 상태를 조회할 수도 있습니다.mediaTimeHistory
: 벽시계 시간 및 미디어 시간 쌍의 기록으로, 미디어의 어떤 부분이 언제 재생되었는지 재구성할 수 있습니다.PlaybackStats.getMediaTimeMsAtRealtimeMs
를 사용하여 지정된 벽시계 시간에 재생 위치를 조회할 수도 있습니다.videoFormatHistory
및audioFormatHistory
: 사용되기 시작한EventTime
로 재생 중에 사용된 동영상 및 오디오 형식의 순서가 지정된 목록입니다.fatalErrorHistory
및nonFatalErrorHistory
: 발생한EventTime
오류와 심각하지 않은 오류의 순서가 지정된 목록입니다. 치명적인 오류는 재생을 종료하는 반면, 심각하지 않은 오류는 복구가 가능했을 수 있습니다.
단일 재생 분석 데이터
이 데이터는 keepHistory=false
를 사용하는 경우에도 PlaybackStatsListener
를 사용하는 경우 자동으로 수집됩니다. 최종 값은 PlaybackStats
Javadoc에서 찾을 수 있는 공개 필드와 getPlaybackStateDurationMs
에서 반환한 재생 상태 기간입니다. 편의를 위해 특정 재생 상태 조합의 지속 시간을 반환하는 getTotalPlayTimeMs
및 getTotalWaitTimeMs
과 같은 메서드도 찾을 수 있습니다.
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();