UsageStatsManager

EXTRA_EVENT_ACTION

static val EXTRA_EVENT_ACTION: String

A String extra, when used with UsageEvents.Event#getExtras, 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.

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

EXTRA_EVENT_CATEGORY

static val EXTRA_EVENT_CATEGORY: String

A String extra, when used with UsageEvents.Event#getExtras, 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.

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

INTERVAL_BEST

static val INTERVAL_BEST: Int

An interval type that will use the best fit interval for the given time range. See queryUsageStats(int,long,long).

Value: 4

INTERVAL_DAILY

static val INTERVAL_DAILY: Int

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

Value: 0

INTERVAL_MONTHLY

static val INTERVAL_MONTHLY: Int

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

Value: 2

INTERVAL_WEEKLY

static val INTERVAL_WEEKLY: Int

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

Value: 1

INTERVAL_YEARLY

static val INTERVAL_YEARLY: Int

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

Value: 3

STANDBY_BUCKET_ACTIVE

static val STANDBY_BUCKET_ACTIVE: Int

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.

Value: 10

STANDBY_BUCKET_FREQUENT

static val STANDBY_BUCKET_FREQUENT: Int

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.

Value: 30

STANDBY_BUCKET_RARE

static val STANDBY_BUCKET_RARE: Int

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.

Value: 40

STANDBY_BUCKET_RESTRICTED

static val STANDBY_BUCKET_RESTRICTED: Int

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.

Value: 45

STANDBY_BUCKET_WORKING_SET

static val STANDBY_BUCKET_WORKING_SET: Int

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.

Value: 20

getAppStandbyBucket

fun getAppStandbyBucket(): Int

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_RESTRICTED, 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.

isAppInactive

fun isAppInactive(packageName: String!): Boolean

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 android.Manifest.permission#PACKAGE_USAGE_STATS to query the inactive state of other apps

queryAndAggregateUsageStats

fun queryAndAggregateUsageStats(
    beginTime: Long, 
    endTime: Long
): MutableMap<String!, UsageStats!>!

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 android.Manifest.permission#PACKAGE_USAGE_STATS

queryConfigurations

fun queryConfigurations(
    intervalType: Int, 
    beginTime: Long, 
    endTime: Long
): MutableList<ConfigurationStats!>!

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 android.Manifest.permission#PACKAGE_USAGE_STATS

queryEventStats

fun queryEventStats(
    intervalType: Int, 
    beginTime: Long, 
    endTime: Long
): MutableList<EventStats!>!

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:

• UsageEvents.Event#SCREEN_INTERACTIVE
• UsageEvents.Event#SCREEN_NON_INTERACTIVE
• UsageEvents.Event#KEYGUARD_SHOWN
• UsageEvents.Event#KEYGUARD_HIDDEN

The caller must have android.Manifest.permission#PACKAGE_USAGE_STATS

queryEvents

fun queryEvents(
    beginTime: Long, 
    endTime: Long
): UsageEvents!

Query for events in the given time range. Events are only kept by the system for a few days.

The caller must have android.Manifest.permission#PACKAGE_USAGE_STATS

queryEvents

fun queryEvents(query: UsageEventsQuery): UsageEvents?

Query for events with specific UsageEventsQuery object. Note: if the user's device is not in an unlocked state (as defined by UserManager#isUserUnlocked()), then null will be returned.
Requires android.Manifest.permission#PACKAGE_USAGE_STATS

queryEventsForSelf

fun queryEventsForSelf(
    beginTime: Long, 
    endTime: Long
): UsageEvents!

Like queryEvents(long,long), but only returns events for the calling package. Note: Starting from Android R, if the user's device is not in an unlocked state (as defined by UserManager#isUserUnlocked()), then null will be returned.

queryUsageStats

fun queryUsageStats(
    intervalType: Int, 
    beginTime: Long, 
    endTime: Long
): MutableList<UsageStats!>!

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

The returned list will contain one or more 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.

The caller must have android.Manifest.permission#PACKAGE_USAGE_STATS