1/*
2 * Copyright (C) 2015 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
17package com.android.tv.analytics;
18
19import com.android.tv.TimeShiftManager;
20import com.android.tv.data.api.Channel;
21
22/** Interface for sending user activity for analysis. */
23public interface Tracker {
24
25    /**
26     * Send the number of channels that doesn't change often.
27     *
28     * <p>Because the number of channels does not change often, this method should not be called
29     * more than once a day.
30     *
31     * @param browsableChannelCount the number of browsable channels.
32     * @param totalChannelCount the number of all channels.
33     */
34    void sendChannelCount(int browsableChannelCount, int totalChannelCount);
35
36    /**
37     * Send data that doesn't change often.
38     *
39     * <p>Because configuration info does not change often, this method should not be called more
40     * than once a day.
41     *
42     * @param info the configuration info.
43     */
44    void sendConfigurationInfo(ConfigurationInfo info);
45
46    /** Sends tracking information for starting the MainActivity. */
47    void sendMainStart();
48
49    /**
50     * Sends tracking for stopping MainActivity.
51     *
52     * @param durationMs The time main activity was "started" in milliseconds.
53     */
54    void sendMainStop(long durationMs);
55
56    /** Sets the screen name and sends a ScreenView hit. */
57    void sendScreenView(String screenName);
58
59    /**
60     * Sends tracking information for starting to view a channel.
61     *
62     * @param channel the current channel
63     * @param tunedByRecommendation True, if the channel was tuned by the recommendation.
64     */
65    void sendChannelViewStart(Channel channel, boolean tunedByRecommendation);
66
67    /**
68     * Sends tracking information for tuning to a channel.
69     *
70     * @param channel The channel that was being tuned.
71     * @param durationMs The time the channel took to tune in milliseconds.
72     */
73    void sendChannelTuneTime(Channel channel, long durationMs);
74
75    /**
76     * Sends tracking information for stopping viewing a channel.
77     *
78     * @param channel The channel that was being watched.
79     * @param durationMs The time the channel was watched in milliseconds.
80     */
81    void sendChannelViewStop(Channel channel, long durationMs);
82
83    /** Sends tracking information for pressing channel up. */
84    void sendChannelUp();
85
86    /** Sends tracking information for pressing channel down. */
87    void sendChannelDown();
88
89    /** Sends tracking information for showing the main menu. */
90    void sendShowMenu();
91
92    /**
93     * Sends tracking for hiding the main menu.
94     *
95     * @param durationMs The duration the menu was shown in milliseconds.
96     */
97    void sendHideMenu(long durationMs);
98
99    /**
100     * Sends tracking for clicking a menu item.
101     *
102     * <p><strong>WARNING</strong> callers must ensure no PII is included in the label.
103     *
104     * @param label The label of the item clicked.
105     */
106    void sendMenuClicked(String label);
107
108    /**
109     * Sends tracking for clicking a menu item.
110     *
111     * <p>NOTE: the tracker will use the english version of the label.
112     *
113     * @param labelResId The resource Id of the label for the menu item.
114     */
115    void sendMenuClicked(int labelResId);
116
117    /** Sends tracking information for showing the Electronic Program Guide (EPG). */
118    void sendShowEpg();
119
120    /** Sends tracking information for clicking an Electronic Program Guide (EPG) item. */
121    void sendEpgItemClicked();
122
123    /**
124     * Sends tracking for hiding the Electronic Program Guide (EPG).
125     *
126     * @param durationMs The duration the EPG was shown in milliseconds.
127     */
128    void sendHideEpg(long durationMs);
129
130    /** Sends tracking information for showing the channel switch view. */
131    void sendShowChannelSwitch();
132
133    /**
134     * Sends tracking for hiding the channel switch view.
135     *
136     * @param durationMs The duration the channel switch view was shown in milliseconds.
137     */
138    void sendHideChannelSwitch(long durationMs);
139
140    /** Sends tracking for each channel number or delimiter pressed. */
141    void sendChannelNumberInput();
142
143    /**
144     * Sends tracking for navigating during channel number input.
145     *
146     * <p>This is sent once per channel input viewing.
147     */
148    void sendChannelInputNavigated();
149
150    /** Sends tracking for channel clicked. */
151    void sendChannelNumberItemClicked();
152
153    /** Sends tracking for channel chosen (tuned) because the channel switch view timed out. */
154    void sendChannelNumberItemChosenByTimeout();
155
156    /** Sends tracking for the reason video is unavailable on a channel. */
157    void sendChannelVideoUnavailable(Channel channel, int reason);
158
159    /**
160     * Sends HDMI AC3 passthrough capabilities.
161     *
162     * @param isSupported {@code true} if the feature is supported; otherwise {@code false}.
163     */
164    void sendAc3PassthroughCapabilities(boolean isSupported);
165
166    /**
167     * Sends tracking for input a connection failure.
168     *
169     * <p><strong>WARNING</strong> callers must ensure no PII is included in the inputId.
170     *
171     * @param inputId the input the failure happened on
172     */
173    void sendInputConnectionFailure(String inputId);
174
175    /**
176     * Sends tracking for input disconnected.
177     *
178     * <p><strong>WARNING</strong> callers must ensure no PII is included in the inputId.
179     *
180     * @param inputId the input the failure happened on
181     */
182    void sendInputDisconnected(String inputId);
183
184    /** Sends tracking information for showing the input selection view. */
185    void sendShowInputSelection();
186
187    /**
188     * Sends tracking for hiding the input selection view.
189     *
190     * @param durationMs The duration the input selection view was shown in milliseconds.
191     */
192    void sendHideInputSelection(long durationMs);
193
194    /**
195     * Sends tracking for input selected by the selection view.
196     *
197     * <p><strong>WARNING</strong> callers must ensure no PII is included in the label.
198     *
199     * @param inputLabel the label of the TV input selected
200     */
201    void sendInputSelected(String inputLabel);
202
203    /**
204     * Sends tracking information for showing a side panel.
205     *
206     * @param trackerLabel the label of the side panel.
207     */
208    void sendShowSidePanel(HasTrackerLabel trackerLabel);
209
210    /**
211     * Sends tracking for hiding a side panel.
212     *
213     * @param trackerLabel The label of the side panel
214     * @param durationMs The duration the side panel was shown in milliseconds.
215     */
216    void sendHideSidePanel(HasTrackerLabel trackerLabel, long durationMs);
217
218    /**
219     * Sends time shift action (pause, ff, etc).
220     *
221     * @param actionId The {@link com.android.tv.TimeShiftManager.TimeShiftActionId}
222     */
223    void sendTimeShiftAction(@TimeShiftManager.TimeShiftActionId int actionId);
224}
225