https://github.com/cap-go/capacitor-android-usagestatsmanager
Capacitor plugin to get Android app usage stats natively
https://github.com/cap-go/capacitor-android-usagestatsmanager
capacitor ionic plugin
Last synced: about 1 month ago
JSON representation
Capacitor plugin to get Android app usage stats natively
- Host: GitHub
- URL: https://github.com/cap-go/capacitor-android-usagestatsmanager
- Owner: Cap-go
- License: mpl-2.0
- Created: 2025-04-08T02:22:46.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-20T12:42:21.000Z (about 2 months ago)
- Last Synced: 2026-04-20T13:51:00.871Z (about 2 months ago)
- Topics: capacitor, ionic, plugin
- Language: JavaScript
- Homepage: https://capgo.app
- Size: 865 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# @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`:
```xml
```
## 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
```bash
npm install @capgo/capacitor-android-usagestatsmanager
npx cap sync
```
## API
* [`queryAndAggregateUsageStats(...)`](#queryandaggregateusagestats)
* [`isUsageStatsPermissionGranted()`](#isusagestatspermissiongranted)
* [`openUsageStatsSettings()`](#openusagestatssettings)
* [`queryAllPackages()`](#queryallpackages)
* [`getPluginVersion()`](#getpluginversion)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
Capacitor plugin for accessing Android UsageStatsManager API.
### queryAndAggregateUsageStats(...)
```typescript
queryAndAggregateUsageStats(options: UsageStatsOptions) => Promise>
```
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()
```typescript
isUsageStatsPermissionGranted() => Promise
```
Checks if the usage stats permission is granted.
**Returns:** Promise<UsageStatsPermissionResult>
**Since:** 1.0.0
--------------------
### openUsageStatsSettings()
```typescript
openUsageStatsSettings() => Promise
```
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()
```typescript
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()
```typescript
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;
}