@capgo/capacitor-android-usagestatsmanager

Read Android app usage statistics from your Capacitor app with the UsageStatsManager API: screen time per app, usage intervals and raw usage events. Built for digital wellbeing, parental control and analytics apps.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-android-usagestatsmanager in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-android-usagestatsmanager to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Aggregated usage: queryAndAggregateUsageStats() returns per-app usage for a time range.
• Interval stats: queryUsageStats() returns stats for daily, weekly, monthly or yearly intervals.
• Raw events: queryEvents() reads the usage event log for a time range.
• Installed apps: queryAllPackages() lists packages installed on the device.
• Permission helpers: isUsageStatsPermissionGranted() and openUsageStatsSettings() guide users to grant usage access.
• Platforms: Android. Android only. Web methods throw.

Description

Exposes the Android's UsageStatsManager SDK to Capacitor

Why Android UsageStatsManager?

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.

Usage

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" />

Documentation

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

Compatibility

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.

Install

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

API

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

Capacitor plugin for accessing Android UsageStatsManager API.

queryAndAggregateUsageStats(...)

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(...)

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(...)

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()

isUsageStatsPermissionGranted() => Promise<UsageStatsPermissionResult>

Checks if the usage stats permission is granted.

Returns: Promise<UsageStatsPermissionResult>

Since: 1.0.0

openUsageStatsSettings()

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(...)

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()

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

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

UsageStats

Usage statistics for an Android app.

UsageStatsOptions

Options for querying usage statistics.

QueryUsageStatsResult

Result of a queryUsageStats call.

QueryUsageStatsOptions

Options for querying per-interval usage statistics.

QueryEventsResult

Result of a queryEvents call.

UsageEvent

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.

QueryEventsOptions

Options for querying the raw usage event log.

UsageStatsPermissionResult

Result of a usage stats permission check.

PackageInfo

Represents basic information about an installed package.

QueryAllPackagesOptions

Options for querying installed packages.

Type Aliases

Record

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

{ [P in K]: T; }