@capgo/capacitor-android-usagestatsmanager

Exposes the Android's UsageStatsManager SDK to Capacitor

The only plugin exposing Android's UsageStatsManager API to Capacitor - this Android API was not supported by any plugin before:

• App usage tracking - Monitor which apps users open and for how long
• Screen time analytics - Build parental controls and digital wellbeing features
• Exact-window events - Query raw lifecycle events when you need foreground time clipped to a specific range
• Package information - Query all installed apps on the device
• Time-based queries - Get usage stats for any time range

Perfect for parental control apps, digital wellbeing tools, productivity trackers, and screen time managers.

Requires the following permissions in your AndroidManifest.xml:

<uses-permission android:name="android.permission.PACKAGE_USAGE_STATS"
    tools:ignore="ProtectedPermissions" />
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"
    tools:ignore="QueryAllPackagesPermission" />

The most complete doc is available here: https://capgo.app/docs/plugins/android-usagestatsmanager/

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-android-usagestatsmanager` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-android-usagestatsmanager
npx cap sync

• queryAndAggregateUsageStats(...)
• queryUsageStats(...)
• queryEvents(...)
• isUsageStatsPermissionGranted()
• openUsageStatsSettings()
• queryAllPackages(...)
• getPluginVersion()
• Interfaces
• Type Aliases

Capacitor plugin for accessing Android UsageStatsManager API.

queryAndAggregateUsageStats(options: UsageStatsOptions) => Promise<Record<string, UsageStats>>

Queries and aggregates usage stats for the given time range.

Android reads pre-aggregated daily/weekly/monthly/yearly buckets and sums every bucket that intersects [beginTime, endTime), without clipping to it. totalTimeInForeground can therefore include usage from outside the window. Use queryUsageStats for the unmerged per-interval buckets, or queryEvents for timestamped lifecycle events in the requested range.

Returns: Promise<Record<string, UsageStats>>

Since: 1.0.0

queryUsageStats(options: QueryUsageStatsOptions) => Promise<QueryUsageStatsResult>

Queries usage stats for the given interval type and time range.

Wraps Android UsageStatsManager.queryUsageStats. Unlike queryAndAggregateUsageStats, this does not merge buckets: the result is one UsageStats object per package per overlapping interval. Android may expand [beginTime, endTime) to the nearest whole interval period, so totalTimeInForeground can include usage from outside the window.

On Android R (API 30) and above, the OS returns no data while the user is locked; this plugin then resolves { stats: [] }, which must not be treated as zero foreground usage.

This uses the same PACKAGE_USAGE_STATS permission as queryAndAggregateUsageStats.

Returns: Promise<QueryUsageStatsResult>

Since: 8.1.3

queryEvents(options: QueryEventsOptions) => Promise<QueryEventsResult>

Queries the raw usage event log for the given time range.

Returns lifecycle events whose timestamps fall in [beginTime, endTime). Android does not emit a synthetic event for "already in foreground at beginTime" or "still in foreground at endTime". To measure duration across those boundaries, pass an earlier beginTime as lookback and clip locally: treat an unmatched pause as starting at the window start, and an unmatched resume as ending at the window end.

Android retains events for only a few days. Older ranges may return an incomplete or empty list; that is not the same as zero foreground usage. On Android R (API 30) and above, the OS also returns no events while the user is locked; this plugin then resolves { events: [] }, which likewise must not be treated as zero foreground usage.

Callers can sum resumed-to-paused intervals from the returned events. Do not treat DEVICE_SHUTDOWN as a pause: it is a reset marker, not an interval close. This uses the same PACKAGE_USAGE_STATS permission as queryAndAggregateUsageStats.

Only lifecycle events are returned, to keep the bridge payload small:

• 1 — ACTIVITY_RESUMED / MOVE_TO_FOREGROUND
• 2 — ACTIVITY_PAUSED / MOVE_TO_BACKGROUND
• 23 — ACTIVITY_STOPPED
• 26 — DEVICE_SHUTDOWN (device-wide reset marker; still returned when packageName is set. Android typically reports package "android". packageName is omitted if the OS does not attach one. The timestamp is the last UsageStats persist before shutdown, not the actual power-off. Open resume events without a matching pause between this marker and the next boot have unknown duration and must be ignored.)

Returns: Promise<QueryEventsResult>

Since: 8.1.3

isUsageStatsPermissionGranted() => Promise<UsageStatsPermissionResult>

Checks if the usage stats permission is granted.

Returns: Promise<UsageStatsPermissionResult>

Since: 1.0.0

openUsageStatsSettings() => Promise<void>

Open the usage stats settings screen. This will open the usage stats settings screen, which allows the user to grant the usage stats permission. This will always open the settings screen, even if the permission is already granted.

Since: 1.0.0

queryAllPackages(options?: QueryAllPackagesOptions | undefined) => Promise<{ packages: PackageInfo[]; }>

Queries all installed packages on the device. Requires the QUERY_ALL_PACKAGES permission.

Returns: Promise<{ packages: PackageInfo[]; }>

Since: 1.2.0

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Usage statistics for an Android app.

Options for querying usage statistics.

Result of a queryUsageStats call.

Options for querying per-interval usage statistics.

Result of a queryEvents call.

Represents a single usage event.

queryEvents currently populates className, timeStamp, and eventType. packageName is set when Android attaches one (DEVICE_SHUTDOWN usually uses "android") and omitted otherwise. Other fields remain optional for compatibility.

Options for querying the raw usage event log.

Result of a usage stats permission check.

Represents basic information about an installed package.

Options for querying installed packages.

Construct a type with a set of properties K of type T

{ [P in K]: T; }