Developers
Play ConsoleUsageStatsManager
public
final
class
UsageStatsManager
extends Object
| java.lang.Object | |
| ↳ | android.app.usage.UsageStatsManager |
Provides access to device usage history and statistics. Usage data is aggregated into time intervals: days, weeks, months, and years.
When requesting usage data since a particular time, the request might look something like this:
PAST REQUEST_TIME TODAY FUTURE
————————————————————————————||———————————————————————————¦-----------------------|
YEAR || ¦ |
————————————————————————————||———————————————————————————¦-----------------------|
MONTH | || MONTH ¦ |
——————————————————|—————————||———————————————————————————¦-----------------------|
| WEEK | WEEK|| | WEEK | WE¦EK | WEEK |
————————————————————————————||———————————————————|———————¦-----------------------|
|| |DAY|DAY|DAY|DAY¦DAY|DAY|DAY|DAY|DAY|DAY|
————————————————————————————||———————————————————————————¦-----------------------|
A request for data in the middle of a time interval will include that interval.
NOTE: This API requires the permission android.permission.PACKAGE_USAGE_STATS.
However, declaring the permission implies intention to use the API and the user of the device
still needs to grant permission through the Settings application.
See ACTION_USAGE_ACCESS_SETTINGS
Instances of this class must be obtained using Context.getSystemService(Class) with the argument UsageStatsManager.class or Context.getSystemService(String) with the argument Context.USAGE_STATS_SERVICE.
Summary
Constants | |
|---|---|
int |
INTERVAL_BEST
An interval type that will use the best fit interval for the given time range. |
int |
INTERVAL_DAILY
An interval type that spans a day. |
int |
INTERVAL_MONTHLY
An interval type that spans a month. |
int |
INTERVAL_WEEKLY
An interval type that spans a week. |
int |
INTERVAL_YEARLY
An interval type that spans a year. |
int |
STANDBY_BUCKET_ACTIVE
The app was used very recently, currently in use or likely to be used very soon. |
int |
STANDBY_BUCKET_FREQUENT
The app was used in the last few days and/or likely to be used in the next few days. |
int |
STANDBY_BUCKET_RARE
The app has not be used for several days and/or is unlikely to be used for several days. |
int |
STANDBY_BUCKET_WORKING_SET
The app was used recently and/or likely to be used in the next few hours. |
Public methods | |
|---|---|
int
|
getAppStandbyBucket()
Returns the current standby bucket of the calling app. |
boolean
|
isAppInactive(String packageName)
Returns whether the specified app is currently considered inactive. |
Map<String, UsageStats>
|
queryAndAggregateUsageStats(long beginTime, long endTime)
A convenience method that queries for all stats in the given range (using the best interval for that range), merges the resulting data, and keys it by package name. |
List<ConfigurationStats>
|
queryConfigurations(int intervalType, long beginTime, long endTime)
Gets the hardware configurations the device was in for the given time range, aggregated by the specified interval. |
UsageEvents
|
queryEvents(long beginTime, long endTime)
Query for events in the given time range. |
List<UsageStats>
|
queryUsageStats(int intervalType, long beginTime, long endTime)
Gets application usage stats for the given time range, aggregated by the specified interval. |
Inherited methods | |
|---|---|
Constants
INTERVAL_BEST
int INTERVAL_BEST
An interval type that will use the best fit interval for the given time range.
See queryUsageStats(int, long, long).
Constant Value: 4 (0x00000004)
INTERVAL_DAILY
int INTERVAL_DAILY
An interval type that spans a day. See queryUsageStats(int, long, long).
Constant Value: 0 (0x00000000)
INTERVAL_MONTHLY
int INTERVAL_MONTHLY
An interval type that spans a month. See queryUsageStats(int, long, long).
Constant Value: 2 (0x00000002)
INTERVAL_WEEKLY
int INTERVAL_WEEKLY
An interval type that spans a week. See queryUsageStats(int, long, long).
Constant Value: 1 (0x00000001)
INTERVAL_YEARLY
int INTERVAL_YEARLY
An interval type that spans a year. See queryUsageStats(int, long, long).
Constant Value: 3 (0x00000003)
STANDBY_BUCKET_ACTIVE
int STANDBY_BUCKET_ACTIVE
The app was used very recently, currently in use or likely to be used very soon.
See also:
Constant Value: 10 (0x0000000a)
STANDBY_BUCKET_FREQUENT
int STANDBY_BUCKET_FREQUENT
The app was used in the last few days and/or likely to be used in the next few days.
See also:
Constant Value: 30 (0x0000001e)
STANDBY_BUCKET_RARE
int STANDBY_BUCKET_RARE
The app has not be used for several days and/or is unlikely to be used for several days.
See also:
Constant Value: 40 (0x00000028)
STANDBY_BUCKET_WORKING_SET
int STANDBY_BUCKET_WORKING_SET
The app was used recently and/or likely to be used in the next few hours.
See also:
Constant Value: 20 (0x00000014)
Public methods
getAppStandbyBucket
int getAppStandbyBucket ()
Returns the current standby bucket of the calling app. The system determines the standby state of the app based on app usage patterns. Standby buckets determine how much an app will be restricted from running background tasks such as jobs, alarms and certain PendingIntent callbacks.
Restrictions increase progressively from STANDBY_BUCKET_ACTIVE to
STANDBY_BUCKET_RARE, with STANDBY_BUCKET_ACTIVE being the least
restrictive. The battery level of the device might also affect the restrictions.
| Returns | |
|---|---|
int |
the current standby bucket of the calling app. One of STANDBY_BUCKET_* constants.
Value is |
isAppInactive
boolean isAppInactive (String packageName)
Returns whether the specified app is currently considered inactive. This will be true if the app hasn't been used directly or indirectly for a period of time defined by the system. This could be of the order of several hours or days.
| Parameters | |
|---|---|
packageName |
String: The package name of the app to query |
| Returns | |
|---|---|
boolean |
whether the app is currently considered inactive |
queryAndAggregateUsageStats
Map<String, UsageStats> queryAndAggregateUsageStats (long beginTime, long endTime)
A convenience method that queries for all stats in the given range (using the best interval
for that range), merges the resulting data, and keys it by package name.
See queryUsageStats(int, long, long).
| Parameters | |
|---|---|
beginTime |
long: The inclusive beginning of the range of stats to include in the results. |
endTime |
long: The exclusive end of the range of stats to include in the results. |
| Returns | |
|---|---|
Map<String, UsageStats> |
A Map keyed by package name
|
queryConfigurations
List<ConfigurationStats> queryConfigurations (int intervalType, long beginTime, long endTime)
Gets the hardware configurations the device was in for the given time range, aggregated by
the specified interval. The results are ordered as in
queryUsageStats(int, long, long).
| Parameters | |
|---|---|
intervalType |
int: The time interval by which the stats are aggregated. |
beginTime |
long: The inclusive beginning of the range of stats to include in the results. |
endTime |
long: The exclusive end of the range of stats to include in the results. |
| Returns | |
|---|---|
List<ConfigurationStats> |
A list of ConfigurationStats
|
queryEvents
UsageEvents queryEvents (long beginTime, long endTime)
Query for events in the given time range. Events are only kept by the system for a few days.
| Parameters | |
|---|---|
beginTime |
long: The inclusive beginning of the range of events to include in the results. |
endTime |
long: The exclusive end of the range of events to include in the results. |
| Returns | |
|---|---|
UsageEvents |
A UsageEvents.
|
queryUsageStats
List<UsageStats> queryUsageStats (int intervalType, long beginTime, long endTime)
Gets application usage stats for the given time range, aggregated by the specified interval.
The returned list will contain a UsageStats object for each package that
has data for an interval that is a subset of the time range given. To illustrate:
intervalType = INTERVAL_YEARLY beginTime = 2013 endTime = 2015 (exclusive) Results: 2013 - com.example.alpha 2013 - com.example.beta 2014 - com.example.alpha 2014 - com.example.beta 2014 - com.example.charlie
| Parameters | |
|---|---|
intervalType |
int: The time interval by which the stats are aggregated. |
beginTime |
long: The inclusive beginning of the range of stats to include in the results. |
endTime |
long: The exclusive end of the range of stats to include in the results. |
| Returns | |
|---|---|
List<UsageStats> |
A list of UsageStats |
