Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

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

Importieren

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

Quickstart

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`);
}

Beispiel: 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`);
});

Beispiel: 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}`);
});

Häufige Stolperfallen

• Nativer Sync: ausführen npx cap sync nach Plugin-Upgrades.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

API Übersicht

queryAndAggregateUsageStats

Fragt Nutzungsstatistiken für den angegebenen Zeitraum ab und aggregiert diese.

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

Prüft, ob die Berechtigung für Nutzungsstatistiken erteilt wurde.

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

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

openUsageStatsSettings

Öffnet die Einstellungen für Nutzungsstatistiken. Damit wird der Einstellungsbildschirm für Nutzungsstatistiken geöffnet, über den der Nutzer die Berechtigung erteilen kann. Dies öffnet immer den Einstellungsbildschirm, auch wenn die Berechtigung bereits erteilt wurde.

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

await CapacitorUsageStatsManager.openUsageStatsSettings();

queryAllPackages

Fragt alle auf dem Gerät installierten Pakete ab. Erfordert die QUERY_ALL_PACKAGES-Berechtigung.

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

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

Typreferenz

UsageStatsOptions

Optionen für die Abfrage von Nutzungsstatistiken.

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

Nutzungsstatistiken für eine Android-App.

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

Result of a usage stats permission check.

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

PackageInfo

Repräsentiert Basisinformationen über ein installiertes Paket.

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

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit Verwendung von @capgo/capacitor-android-usagestatsmanager für die native Funktion in Verwendung von @capgo/capacitor-android-usagestatsmanager, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.