@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

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

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

Type Aliases

Record

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

{ [P in K]: T; }