Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

UsageStatsManager

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: Most methods on this API require 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 Settings.ACTION_USAGE_ACCESS_SETTINGS. Methods which only return the information for the calling package do not require this permission. E.g. getAppStandbyBucket() and queryEventsForSelf(long, long).

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<StringUsageStats> 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.

List<EventStats> queryEventStats(int intervalType, long beginTime, long endTime)

Gets aggregated event stats for the given time range, aggregated by the specified interval.

UsageEvents queryEvents(long beginTime, long endTime)

Query for events in the given time range.

UsageEvents queryEventsForSelf(long beginTime, long endTime)

Like queryEvents(long, long), but only returns events for the calling package.

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

added in API level 21
public static final 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

added in API level 21
public static final int INTERVAL_DAILY

An interval type that spans a day. See queryUsageStats(int, long, long).

Constant Value: 0 (0x00000000)

INTERVAL_MONTHLY

added in API level 21
public static final int INTERVAL_MONTHLY

An interval type that spans a month. See queryUsageStats(int, long, long).

Constant Value: 2 (0x00000002)

INTERVAL_WEEKLY

added in API level 21
public static final int INTERVAL_WEEKLY

An interval type that spans a week. See queryUsageStats(int, long, long).

Constant Value: 1 (0x00000001)

INTERVAL_YEARLY

added in API level 21
public static final int INTERVAL_YEARLY

An interval type that spans a year. See queryUsageStats(int, long, long).

Constant Value: 3 (0x00000003)

STANDBY_BUCKET_ACTIVE

added in API level 28
public static final int STANDBY_BUCKET_ACTIVE

The app was used very recently, currently in use or likely to be used very soon. Standby bucket values that are ≤ STANDBY_BUCKET_ACTIVE will not be throttled by the system while they are in this bucket. Buckets > STANDBY_BUCKET_ACTIVE will most likely be restricted in some way. For instance, jobs and alarms may be deferred.

Constant Value: 10 (0x0000000a)

STANDBY_BUCKET_FREQUENT

added in API level 28
public static final int STANDBY_BUCKET_FREQUENT

The app was used in the last few days and/or likely to be used in the next few days. Restrictions will apply to these apps, such as deferral of jobs and alarms. The delays may be greater than for apps in higher buckets (lower bucket value). Bucket values > STANDBY_BUCKET_FREQUENT may additionally have network access limited.

Constant Value: 30 (0x0000001e)

STANDBY_BUCKET_RARE

added in API level 28
public static final int STANDBY_BUCKET_RARE

The app has not be used for several days and/or is unlikely to be used for several days. Apps in this bucket will have the most restrictions, including network restrictions, except during certain short periods (at a minimum, once a day) when they are allowed to execute jobs, access the network, etc.

Constant Value: 40 (0x00000028)

STANDBY_BUCKET_WORKING_SET

added in API level 28
public static final int STANDBY_BUCKET_WORKING_SET

The app was used recently and/or likely to be used in the next few hours. Restrictions will apply to these apps, such as deferral of jobs and alarms.

Constant Value: 20 (0x00000014)

Public methods

getAppStandbyBucket

added in API level 28
public 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 and alarms.

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.

Apps in buckets ≤ STANDBY_BUCKET_ACTIVE have no standby restrictions imposed. Apps in buckets > STANDBY_BUCKET_FREQUENT may have network access restricted when running in the background.

The standby state of an app can change at any time either due to a user interaction or a system interaction or some algorithm determining that the app can be restricted for a period of time before the user has a need for it.

You can also query the recent history of standby bucket changes by calling queryEventsForSelf(long, long) and searching for UsageEvents.Event.STANDBY_BUCKET_CHANGED.

Returns
int the current standby bucket of the calling app. One of STANDBY_BUCKET_* constants.

Value is STANDBY_BUCKET_ACTIVE, STANDBY_BUCKET_WORKING_SET, STANDBY_BUCKET_FREQUENT or STANDBY_BUCKET_RARE.

isAppInactive

added in API level 23
public 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

added in API level 21
public Map<StringUsageStats> 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).

The caller must have Manifest.permission.PACKAGE_USAGE_STATS

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<StringUsageStats> A Map keyed by package name

queryConfigurations

added in API level 21
public 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).

The caller must have Manifest.permission.PACKAGE_USAGE_STATS

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

queryEventStats

added in API level 28
public List<EventStats> queryEventStats (int intervalType, 
                long beginTime, 
                long endTime)

Gets aggregated event stats for the given time range, aggregated by the specified interval.

The returned list will contain a EventStats object for each event type that is being aggregated and has data for an interval that is a subset of the time range given.

The current event types that will be aggregated here are:

The caller must have Manifest.permission.PACKAGE_USAGE_STATS

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<EventStats> A list of EventStats

queryEvents

added in API level 21
public 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.

The caller must have Manifest.permission.PACKAGE_USAGE_STATS

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.

queryEventsForSelf

added in API level 28
public UsageEvents queryEventsForSelf (long beginTime, 
                long endTime)

Like queryEvents(long, long), but only returns events for the calling package.

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 object.

queryUsageStats

added in API level 21
public 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
 

The caller must have Manifest.permission.PACKAGE_USAGE_STATS

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