Getting Started

Installation

npm

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

yarn

yarn add @capgo/capacitor-android-usagestatsmanager
npx cap sync

pnpm

pnpm add @capgo/capacitor-android-usagestatsmanager
npx cap sync

bun

bun add @capgo/capacitor-android-usagestatsmanager
npx cap sync

Platform Configuration

Android

Add the required permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.PACKAGE_USAGE_STATS" />
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />

Usage Example

import { AndroidUsageStatsManager } from '@capgo/capacitor-android-usagestatsmanager';

// Check if permission is granted
const permissionResult = await AndroidUsageStatsManager.isUsageStatsPermissionGranted();
if (!permissionResult.granted) {
  // Open settings to grant permission
  await AndroidUsageStatsManager.openUsageStatsSettings();
  return;
}

// Query usage statistics for the last 7 days
const statsOptions = {
  intervalType: 0, // INTERVAL_DAILY
  startTime: Date.now() - (7 * 24 * 60 * 60 * 1000), // 7 days ago
  endTime: Date.now()
};

const usageStats = await AndroidUsageStatsManager.queryAndAggregateUsageStats(statsOptions);
console.log('Usage statistics:', usageStats);

// Get all installed packages
const packages = await AndroidUsageStatsManager.queryAllPackages();
console.log('Installed packages:', packages);

API Reference

isUsageStatsPermissionGranted()

isUsageStatsPermissionGranted() => Promise<{ granted: boolean }>

Check if the PACKAGE_USAGE_STATS permission is granted.

Returns: Promise<{ granted: boolean }>

openUsageStatsSettings()

openUsageStatsSettings() => Promise<void>

Open the system settings page for granting usage stats permission.

queryAndAggregateUsageStats(options)

queryAndAggregateUsageStats(options: UsageStatsOptions) => Promise<UsageStatsResult>

Query detailed usage statistics for installed apps.

Param	Type
options	UsageStatsOptions

Returns: Promise<UsageStatsResult>

queryAllPackages()

queryAllPackages() => Promise<PackagesResult>

Get information about all installed packages on the device.

Returns: Promise<PackagesResult>

Interfaces

UsageStatsOptions

Prop	Type	Description
intervalType	number	Interval type (0=DAILY, 1=WEEKLY, 2=MONTHLY, etc.)
startTime	number	Start time in milliseconds
endTime	number	End time in milliseconds

UsageStatsResult

Contains usage statistics data for each app:

• App usage time and frequency
• First and last time used
• Total time in foreground
• Launch count

PackagesResult

Contains information about installed packages:

• Package name and version
• Installation time
• App labels and icons
• System vs user apps

Permission Handling

The plugin requires special permissions that cannot be granted through normal runtime permission requests:

1. PACKAGE_USAGE_STATS: Allows access to usage statistics
2. QUERY_ALL_PACKAGES: Required for package information (Android 11+)

Users must manually grant these permissions through system settings. Use openUsageStatsSettings() to direct users to the appropriate settings page.

Best Practices

• Always check permission status before querying usage statistics
• Handle permission denial gracefully with user-friendly messages
• Consider user privacy when collecting usage data
• Implement proper data handling and storage practices
• Follow Google Play policies for usage data collection

Use Cases

• Digital wellbeing apps: Monitor screen time and app usage
• Parental controls: Track children’s device usage
• Productivity apps: Analyze work patterns and focus time
• Analytics: Understand user behavior and app engagement