1 /* 2 * Copyright (C) 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.google.android.exoplayer2.analytics; 17 18 import com.google.android.exoplayer2.Player.DiscontinuityReason; 19 import com.google.android.exoplayer2.Timeline; 20 import com.google.android.exoplayer2.analytics.AnalyticsListener.EventTime; 21 import com.google.android.exoplayer2.source.MediaSource.MediaPeriodId; 22 23 /** 24 * Manager for active playback sessions. 25 * 26 * <p>The manager keeps track of the association between window index and/or media period id to 27 * session identifier. 28 */ 29 public interface PlaybackSessionManager { 30 31 /** A listener for session updates. */ 32 interface Listener { 33 34 /** 35 * Called when a new session is created as a result of {@link #updateSessions(EventTime)}. 36 * 37 * @param eventTime The {@link EventTime} at which the session is created. 38 * @param sessionId The identifier of the new session. 39 */ onSessionCreated(EventTime eventTime, String sessionId)40 void onSessionCreated(EventTime eventTime, String sessionId); 41 42 /** 43 * Called when a session becomes active, i.e. playing in the foreground. 44 * 45 * @param eventTime The {@link EventTime} at which the session becomes active. 46 * @param sessionId The identifier of the session. 47 */ onSessionActive(EventTime eventTime, String sessionId)48 void onSessionActive(EventTime eventTime, String sessionId); 49 50 /** 51 * Called when a session is interrupted by ad playback. 52 * 53 * @param eventTime The {@link EventTime} at which the ad playback starts. 54 * @param contentSessionId The session identifier of the content session. 55 * @param adSessionId The identifier of the ad session. 56 */ onAdPlaybackStarted(EventTime eventTime, String contentSessionId, String adSessionId)57 void onAdPlaybackStarted(EventTime eventTime, String contentSessionId, String adSessionId); 58 59 /** 60 * Called when a session is permanently finished. 61 * 62 * @param eventTime The {@link EventTime} at which the session finished. 63 * @param sessionId The identifier of the finished session. 64 * @param automaticTransitionToNextPlayback Whether the session finished because of an automatic 65 * transition to the next playback item. 66 */ onSessionFinished( EventTime eventTime, String sessionId, boolean automaticTransitionToNextPlayback)67 void onSessionFinished( 68 EventTime eventTime, String sessionId, boolean automaticTransitionToNextPlayback); 69 } 70 71 /** 72 * Sets the listener to be notified of session updates. Must be called before the session manager 73 * is used. 74 * 75 * @param listener The {@link Listener} to be notified of session updates. 76 */ setListener(Listener listener)77 void setListener(Listener listener); 78 79 /** 80 * Returns the session identifier for the given media period id. 81 * 82 * <p>Note that this will reserve a new session identifier if it doesn't exist yet, but will not 83 * call any {@link Listener} callbacks. 84 * 85 * @param timeline The timeline, {@code mediaPeriodId} is part of. 86 * @param mediaPeriodId A {@link MediaPeriodId}. 87 */ getSessionForMediaPeriodId(Timeline timeline, MediaPeriodId mediaPeriodId)88 String getSessionForMediaPeriodId(Timeline timeline, MediaPeriodId mediaPeriodId); 89 90 /** 91 * Returns whether an event time belong to a session. 92 * 93 * @param eventTime The {@link EventTime}. 94 * @param sessionId A session identifier. 95 * @return Whether the event belongs to the specified session. 96 */ belongsToSession(EventTime eventTime, String sessionId)97 boolean belongsToSession(EventTime eventTime, String sessionId); 98 99 /** 100 * Updates or creates sessions based on a player {@link EventTime}. 101 * 102 * @param eventTime The {@link EventTime}. 103 */ updateSessions(EventTime eventTime)104 void updateSessions(EventTime eventTime); 105 106 /** 107 * Updates the session associations to a new timeline. 108 * 109 * @param eventTime The event time with the timeline change. 110 */ handleTimelineUpdate(EventTime eventTime)111 void handleTimelineUpdate(EventTime eventTime); 112 113 /** 114 * Handles a position discontinuity. 115 * 116 * @param eventTime The event time of the position discontinuity. 117 * @param reason The {@link DiscontinuityReason}. 118 */ handlePositionDiscontinuity(EventTime eventTime, @DiscontinuityReason int reason)119 void handlePositionDiscontinuity(EventTime eventTime, @DiscontinuityReason int reason); 120 121 /** 122 * Finishes all existing sessions and calls their respective {@link 123 * Listener#onSessionFinished(EventTime, String, boolean)} callback. 124 * 125 * @param eventTime The event time at which sessions are finished. 126 */ finishAllSessions(EventTime eventTime)127 void finishAllSessions(EventTime eventTime); 128 } 129