UsageStatsManager  |  API reference  |  Android Developers (original) (raw)

public final class UsageStatsManager
extends [Object](/reference/java/lang/Object) ``

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 \u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014||\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014¦-----------------------| YEAR || ¦ | \u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014||\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014¦-----------------------| MONTH | || MONTH ¦ | \u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014|\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014||\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014¦-----------------------| | WEEK | WEEK|| | WEEK | WE¦EK | WEEK | \u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014||\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014|\u2014\u2014\u2014\u2014\u2014\u2014\u2014¦-----------------------| || |DAY|DAY|DAY|DAY¦DAY|DAY|DAY|DAY|DAY|DAY| \u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014||\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014¦-----------------------|

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](/reference/android/provider/Settings#ACTION%5FUSAGE%5FACCESS%5FSETTINGS). Methods which only return the information for the calling package do not require this permission. E.g. [getAppStandbyBucket()](/reference/android/app/usage/UsageStatsManager#getAppStandbyBucket%28%29) and [queryEventsForSelf(long, long)](/reference/android/app/usage/UsageStatsManager#queryEventsForSelf%28long,%20long%29).

Summary

Constants
String EXTRA_EVENT_ACTION A String extra, when used with UsageEvents.Event.getExtras, that indicates the action of the user interaction associated with the event.
String EXTRA_EVENT_CATEGORY A String extra, when used with UsageEvents.Event.getExtras, that indicates the category of the user interaction associated with the event.
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_RESTRICTED The app has not be used for several days, is unlikely to be used for several days, and has been misbehaving in some manner.
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.
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 queryEvents(UsageEventsQuery query) Query for events with specific UsageEventsQuery object.
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
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. finalClass<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

public static final String EXTRA_EVENT_ACTION

A String extra, when used with [UsageEvents.Event.getExtras](/reference/android/app/usage/UsageEvents.Event#getExtras%28%29), that indicates the action of the user interaction associated with the event. The action cannot be more than 127 characters, longer value will be truncated to 127 characters.

Constant Value: "android.app.usage.extra.EVENT_ACTION"

public static final String EXTRA_EVENT_CATEGORY

A String extra, when used with [UsageEvents.Event.getExtras](/reference/android/app/usage/UsageEvents.Event#getExtras%28%29), that indicates the category of the user interaction associated with the event. The category cannot be more than 127 characters, longer value will be truncated to 127 characters.

Constant Value: "android.app.usage.extra.EVENT_CATEGORY"

INTERVAL_BEST

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)](/reference/android/app/usage/UsageStatsManager#queryUsageStats%28int,%20long,%20long%29).

Constant Value: 4 (0x00000004)

INTERVAL_MONTHLY

public static final int INTERVAL_MONTHLY

An interval type that spans a month. See [queryUsageStats(int, long, long)](/reference/android/app/usage/UsageStatsManager#queryUsageStats%28int,%20long,%20long%29).

Constant Value: 2 (0x00000002)

INTERVAL_WEEKLY

public static final int INTERVAL_WEEKLY

An interval type that spans a week. See [queryUsageStats(int, long, long)](/reference/android/app/usage/UsageStatsManager#queryUsageStats%28int,%20long,%20long%29).

Constant Value: 1 (0x00000001)

INTERVAL_YEARLY

public static final int INTERVAL_YEARLY

An interval type that spans a year. See [queryUsageStats(int, long, long)](/reference/android/app/usage/UsageStatsManager#queryUsageStats%28int,%20long,%20long%29).

Constant Value: 3 (0x00000003)

STANDBY_BUCKET_ACTIVE

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](/reference/android/app/usage/UsageStatsManager#STANDBY%5FBUCKET%5FACTIVE) will not be throttled by the system while they are in this bucket. Buckets > [STANDBY_BUCKET_ACTIVE](/reference/android/app/usage/UsageStatsManager#STANDBY%5FBUCKET%5FACTIVE) will most likely be restricted in some way. For instance, jobs and alarms may be deferred.

Constant Value: 10 (0x0000000a)

STANDBY_BUCKET_FREQUENT

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](/reference/android/app/usage/UsageStatsManager#STANDBY%5FBUCKET%5FFREQUENT) may additionally have network access limited.

Constant Value: 30 (0x0000001e)

STANDBY_BUCKET_RARE

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 more 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_RESTRICTED

public static final int STANDBY_BUCKET_RESTRICTED

The app has not be used for several days, is unlikely to be used for several days, and has been misbehaving in some manner. Apps in this bucket will have the most restrictions, including network restrictions and additional restrictions on jobs.

Note: this bucket is not enabled in [Build.VERSION_CODES.R](/reference/android/os/Build.VERSION%5FCODES#R).

Constant Value: 45 (0x0000002d)

STANDBY_BUCKET_WORKING_SET

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

isAppInactive

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. Apps are not considered inactive when the device is charging.

The caller must have [Manifest.permission.PACKAGE_USAGE_STATS](/reference/android/Manifest.permission#PACKAGE%5FUSAGE%5FSTATS) to query the inactive state of other apps

Parameters
packageName String: The package name of the app to query
Returns
boolean whether the app is currently considered inactive or false if querying another app without Manifest.permission.PACKAGE_USAGE_STATS

queryUsageStats

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 one or more [UsageStats](/reference/android/app/usage/UsageStats) objects for each package, with usage data that covers at least the given time range. Note: The begin and end times of the time range may be expanded to the nearest whole interval period.

Note: Starting from [Android R](/reference/android/os/Build.VERSION%5FCODES#R), if the user's device is not in an unlocked state (as defined by [UserManager.isUserUnlocked()](/reference/android/os/UserManager#isUserUnlocked%28%29)), then null will be returned..
Requires [Manifest.permission.PACKAGE_USAGE_STATS](/reference/android/Manifest.permission#PACKAGE%5FUSAGE%5FSTATS)

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. Defined in terms of "Unix time", seeSystem.currentTimeMillis().
endTime long: The exclusive end of the range of stats to include in the results. Defined in terms of "Unix time", see System.currentTimeMillis().
Returns
List<UsageStats> A list of UsageStats