Android APIs
public final class

UsageStatsManager

extends Object
java.lang.Object
   ↳ android.app.usage.UsageStatsManager

Class Overview

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, which is a system-level permission and will not be granted to third-party apps. However, declaring the permission implies intention to use the API and the user of the device can grant permission through the Settings application.

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.
Public Methods
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.
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.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int INTERVAL_BEST

Added in API level 21

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

Constant Value: 4 (0x00000004)

public static final int INTERVAL_DAILY

Added in API level 21

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

Constant Value: 0 (0x00000000)

public static final int INTERVAL_MONTHLY

Added in API level 21

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

Constant Value: 2 (0x00000002)

public static final int INTERVAL_WEEKLY

Added in API level 21

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

Constant Value: 1 (0x00000001)

public static final int INTERVAL_YEARLY

Added in API level 21

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

Constant Value: 3 (0x00000003)

Public Methods

public Map<StringUsageStats> queryAndAggregateUsageStats (long beginTime, long endTime)

Added in API level 21

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 The inclusive beginning of the range of stats to include in the results.
endTime The exclusive end of the range of stats to include in the results.
Returns
  • A Map keyed by package name, or null if no stats are available.

public List<ConfigurationStats> queryConfigurations (int intervalType, long beginTime, long endTime)

Added in API level 21

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 The time interval by which the stats are aggregated.
beginTime The inclusive beginning of the range of stats to include in the results.
endTime The exclusive end of the range of stats to include in the results.
Returns

public UsageEvents queryEvents (long beginTime, long endTime)

Added in API level 21

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

NOTE: The last few minutes of the event log will be truncated to prevent abuse by applications.

Parameters
beginTime The inclusive beginning of the range of events to include in the results.
endTime The exclusive end of the range of events to include in the results.
Returns

public List<UsageStats> queryUsageStats (int intervalType, long beginTime, long endTime)

Added in API level 21

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 The time interval by which the stats are aggregated.
beginTime The inclusive beginning of the range of stats to include in the results.
endTime The exclusive end of the range of stats to include in the results.
Returns
  • A list of UsageStats or null if none are available.