rn-app-usage-stats

Android app usage statistics API for React Native using TurboModules.

Installation

npm install rn-app-usage-stats

Android Permissions

This library requires Android's Usage Access permission to query app usage statistics.

The permission cannot be requested through the standard Android runtime permission dialog. The library opens the system Usage Access Settings so the user can grant access.

Usage

import {
  requestUsageStatsPermission,
  hasUsageStatsPermission,
  queryAppUsageSessions,
} from 'rn-app-usage-stats';

const granted = await requestUsageStatsPermission();

if (granted) {
  const endTime = Date.now();
  const startTime = endTime - 24 * 60 * 60 * 1000;

  const sessions = await queryAppUsageSessions(startTime, endTime);

  console.log(sessions);
}

Check Permission

You can check whether Usage Access permission has already been granted:

const granted = await hasUsageStatsPermission();

console.log('Usage stats permission:', granted);

Request Permission

If permission has not been granted, call:

const granted = await requestUsageStatsPermission();

This opens the Android Usage Access Settings. The returned promise resolves to true when the user grants permission and false otherwise.

Query App Usage Sessions

const endTime = Date.now();
const startTime = endTime - 24 * 60 * 60 * 1000;

const sessions = await queryAppUsageSessions(startTime, endTime);

The result is grouped by package name:

{
  'com.google.android.youtube': [
    {
      packageName: 'com.google.android.youtube',
      startTime: 1755061200000,
      endTime: 1755061500000,
    },
  ],
  'com.android.chrome': [
    {
      packageName: 'com.android.chrome',
      startTime: 1755061800000,
      endTime: 1755062100000,
    },
  ],
}

Each usage session contains:

export type AppUsageStats = {
  packageName: string;
  startTime: number;
  endTime: number;
};

startTime and endTime are Unix timestamps in milliseconds.

API

hasUsageStatsPermission()

hasUsageStatsPermission(): Promise<boolean>

Returns whether the application currently has Android Usage Access permission.

requestUsageStatsPermission()

requestUsageStatsPermission(): Promise<boolean>

Opens Android Usage Access Settings and resolves with the resulting permission state when the user returns to the application.

queryAppUsageSessions()

queryAppUsageSessions(
  startTime: number,
  endTime: number
): Promise<Record<string, AppUsageStats[]>>

Queries foreground application sessions within the specified time range and groups the results by package name.

queryAppUsageSessionsByPackageName()

queryAppUsageSessionsByPackageName(
  packageName: string,
  startRange: number,
  endRange: number
): Promise<AppUsageStats[]>

Queries real foreground application sessions for an exact Android package name.

queryAggregatedUsageStats()

queryAggregatedUsageStats(
  startRange: number,
  endRange: number
): Promise<AppUsageStatsAggregated[]>

Queries usage statistics aggregated across the specified time range. Android selects the best interval for the range, merges interval buckets, and returns one record per package.

queryAggregatedUsageStatsByPackageName()

queryAggregatedUsageStatsByPackageName(
  packageName: string,
  startRange: number,
  endRange: number
): Promise<AppUsageStatsAggregated[]>

Queries usage statistics aggregated across the specified time range for a specific package.

queryUsageApps()

queryUsageApps(
  startRange: number,
  endRange: number
): Promise<Array<{ appName: string; packageName: string }>>

Returns the display name and package name of apps with foreground usage in the requested range. It does not scan the complete installed-app inventory.

Android Support

This library is currently intended for Android and uses Android's UsageStatsManager APIs.

Usage statistics are subject to Android's Usage Access permission and the behavior of the Android version running on the device.

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library