快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-android-usagestatsmanager` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

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

导入

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

快速入门

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

const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;
const now = Date.now();
const stats = await CapacitorUsageStatsManager.queryAndAggregateUsageStats({
  beginTime: oneDayAgo,
  endTime: now,
  packageName: 'com.example.app',
});

for (const [packageName, usageData] of Object.entries(stats)) {
  console.log(`${packageName}: ${usageData.totalTimeInForeground}ms`);
}

示例：queryUsageStats

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

const startOfDay = new Date().setHours(0, 0, 0, 0);
const { stats } = await CapacitorUsageStatsManager.queryUsageStats({
  intervalType: 0, // INTERVAL_DAILY
  beginTime: startOfDay,
  endTime: Date.now(),
  packageName: 'com.example.app',
});
stats.forEach((bucket) => {
  console.log(`${bucket.packageName}: ${bucket.totalTimeInForeground}ms`);
});

示例：queryEvents

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

const startOfDay = new Date().setHours(0, 0, 0, 0);
const { events } = await CapacitorUsageStatsManager.queryEvents({
  beginTime: startOfDay,
  endTime: Date.now(),
  packageName: 'com.example.app',
});
events.forEach((event) => {
  console.log(`${event.packageName} type=${event.eventType} at ${event.timeStamp}`);
});

常见坑点

• 原生同步：运行 npx cap sync 在插件升级后。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

API 概览

queryAndAggregateUsageStats

查询并聚合指定时间范围内的使用统计数据。

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

const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;
const now = Date.now();
const stats = await CapacitorUsageStatsManager.queryAndAggregateUsageStats({
  beginTime: oneDayAgo,
  endTime: now
});

for (const [packageName, usageData] of Object.entries(stats)) {
  console.log(`${packageName}: ${usageData.totalTimeInForeground}ms`);
}

isUsageStatsPermissionGranted

检查是否已授予使用统计权限。

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

const { granted } = await CapacitorUsageStatsManager.isUsageStatsPermissionGranted();
if (!granted) {
  await CapacitorUsageStatsManager.openUsageStatsSettings();
}

openUsageStatsSettings

打开使用统计设置界面。 这将打开使用统计设置界面，允许用户授予使用统计权限。 即使权限已授予，此操作也始终会打开设置界面。

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

await CapacitorUsageStatsManager.openUsageStatsSettings();

queryAllPackages

查询设备上所有已安装的包。 需要 QUERY_ALL_PACKAGES 权限。

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

const { packages } = await CapacitorUsageStatsManager.queryAllPackages();
packages.forEach(pkg => {
  console.log(`${pkg.appName} (${pkg.packageName}): v${pkg.versionName}`);
});

类型参考

UsageStatsOptions

查询使用统计数据的配置选项。

export interface UsageStatsOptions {
  /**
   * The inclusive beginning of the range of stats to include in the results.
   * Defined in terms of "Unix time"
   */
  beginTime: number;

  /**
   * The exclusive end of the range of stats to include in the results.
   * Defined in terms of "Unix time"
   */
  endTime: number;
}

UsageStats

Android 应用的使用统计数据。

export interface UsageStats {
  /**
   * The first timestamp of the usage stats.
   */
  firstTimeStamp: number;
  /**
   * The last timestamp of the usage stats.
   */
  lastTimeStamp: number;
  /**
   * Only available on Android Q (API level 29) and above.
   * Will be undefined on lower Android versions.
   */
  lastTimeForegroundServiceUsed?: number;
  /**
   * The last time the app was used.
   */
  lastTimeUsed: number;
  /**
   * Only available on Android Q (API level 29) and above.
   * Will be undefined on lower Android versions.
   */
  lastTimeVisible?: number;
  /**
   * The name of the package.
   */
  packageName: string;
  /**
   * Only available on Android Q (API level 29) and above.
   * Will be undefined on lower Android versions.
   */
  totalForegroundServiceUsed?: number;
  /**
   * The total time the app was in the foreground.
   */
  totalTimeInForeground: number;
  /**
   * Only available on Android Q (API level 29) and above.
   * Will be undefined on lower Android versions.
   */
  totalTimeVisible?: number;
}

UsageStatsPermissionResult

使用统计权限检查的结果。

export interface UsageStatsPermissionResult {
  /**
   * Whether the usage stats permission is granted.
   */
  granted: boolean;
}

PackageInfo

表示已安装包的基本信息。

export interface PackageInfo {
  /** Package name */
  packageName: string;
  /** App display name */
  appName: string;
  /** Version name string */
  versionName: string;
  /** Version code number */
  versionCode: number;
  /** First install time in milliseconds since epoch */
  firstInstallTime: number;
  /** Last update time in milliseconds since epoch */
  lastUpdateTime: number;
}

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 要规划 dashboard 和 API 操作，请将其连接到 使用 @capgo/capacitor-android-usagestatsmanager 若要在 @capgo/capacitor-android-usagestatsmanager 中使用原生能力， API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节，以及 设备 有关 Devices 的实现细节。