@capgo/capacitor-android-usagestatsmanager

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
• 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

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

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

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | -------------------------------------- | | options | UsageStatsOptions | - The time range options for the query |

Returns: Promise<Record<string, UsageStats>>

Since: 1.0.0

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.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------------- | ------------------------- | | options | QueryAllPackagesOptions | - Optional query settings |

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.

| Prop | Type | Description | | ----------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- | | firstTimeStamp | number | The first timestamp of the usage stats. | | lastTimeStamp | number | The last timestamp of the usage stats. | | lastTimeForegroundServiceUsed | number | Only available on Android Q (API level 29) and above. Will be undefined on lower Android versions. | | lastTimeUsed | number | The last time the app was used. | | lastTimeVisible | number | Only available on Android Q (API level 29) and above. Will be undefined on lower Android versions. | | packageName | string | The name of the package. | | totalForegroundServiceUsed | number | Only available on Android Q (API level 29) and above. Will be undefined on lower Android versions. | | totalTimeInForeground | number | The total time the app was in the foreground. | | totalTimeVisible | number | Only available on Android Q (API level 29) and above. Will be undefined on lower Android versions. |

UsageStatsOptions

Options for querying usage statistics.

| Prop | Type | Description | | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------- | | beginTime | number | The inclusive beginning of the range of stats to include in the results. Defined in terms of "Unix time" | | endTime | number | The exclusive end of the range of stats to include in the results. Defined in terms of "Unix time" |

UsageStatsPermissionResult

Result of a usage stats permission check.

| Prop | Type | Description | | ------------- | -------------------- | ---------------------------------------------- | | granted | boolean | Whether the usage stats permission is granted. |

PackageInfo

Represents basic information about an installed package.

| Prop | Type | Description | Since | | ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | packageName | string | Package name | | | appName | string | App display name | | | versionName | string | Version name string | | | versionCode | number | Version code number | | | firstInstallTime | number | First install time in milliseconds since epoch | | | lastUpdateTime | number | Last update time in milliseconds since epoch | | | category | number | Application category from ApplicationInfo.category. Only available on Android 8.0 (API level 26) and above. Common values: - 0 — undefined - 1 — game - 2 — audio - 3 — video - 4 — image - 5 — social - 6 — news - 7 — maps - 8 — productivity | 8.0.33 | | icon | string | App icon as a base64 data URL (data:image/png;base64,...). Only present when queryAllPackages({ includeIcon: true }) is used. | 8.0.33 |

QueryAllPackagesOptions

Options for querying installed packages.

| Prop | Type | Description | Default | | ----------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | includeIcon | boolean | When true, includes each app's launcher icon as a base64 data URL. Defaults to false because icons significantly increase the response size. | false |

Type Aliases

Record

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

{ [P in K]: T; }