Démarrage

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

Configuration de plateforme

Android

Ajoutez les permissions requises à votre android/app/src/main/AndroidManifest.xml :

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

Exemple d’utilisation

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

Référence API

isUsageStatsPermissionGranted()

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

Vérifier si la permission PACKAGE_USAGE_STATS est accordée.

Retourne : Promise<{ granted: boolean }>

openUsageStatsSettings()

openUsageStatsSettings() => Promise<void>

Ouvrir la page des paramètres système pour accorder la permission de statistiques d’utilisation.

queryAndAggregateUsageStats(options)

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

Interroger les statistiques d’utilisation détaillées pour les applications installées.

Param	Type
options	UsageStatsOptions

Retourne : Promise<UsageStatsResult>

queryAllPackages()

queryAllPackages() => Promise<PackagesResult>

Obtenir des informations sur tous les packages installés sur l’appareil.

Retourne : Promise<PackagesResult>

Interfaces

UsageStatsOptions

Prop	Type	Description
intervalType	number	Type d’intervalle (0=DAILY, 1=WEEKLY, 2=MONTHLY, etc.)
startTime	number	Heure de début en millisecondes
endTime	number	Heure de fin en millisecondes

UsageStatsResult

Contient les données de statistiques d’utilisation pour chaque application :

• Temps d’utilisation et fréquence de l’application
• Première et dernière fois utilisée
• Temps total au premier plan
• Nombre de lancements

PackagesResult

Contient des informations sur les packages installés :

• Nom et version du package
• Heure d’installation
• Libellés et icônes d’application
• Applications système vs utilisateur

Gestion des permissions

Le plugin nécessite des permissions spéciales qui ne peuvent pas être accordées via des demandes de permission d’exécution normales :

1. PACKAGE_USAGE_STATS : Permet d’accéder aux statistiques d’utilisation
2. QUERY_ALL_PACKAGES : Requis pour les informations de package (Android 11+)

Les utilisateurs doivent accorder manuellement ces permissions via les paramètres système. Utilisez openUsageStatsSettings() pour diriger les utilisateurs vers la page de paramètres appropriée.

Bonnes pratiques

• Vérifiez toujours l’état de la permission avant d’interroger les statistiques d’utilisation
• Gérez le refus de permission avec élégance avec des messages conviviaux
• Tenez compte de la vie privée de l’utilisateur lors de la collecte de données d’utilisation
• Implémentez des pratiques appropriées de gestion et de stockage des données
• Suivez les politiques de Google Play pour la collecte de données d’utilisation

Cas d’utilisation

• Applications de bien-être numérique : Surveiller le temps d’écran et l’utilisation des applications
• Contrôles parentaux : Suivre l’utilisation de l’appareil des enfants
• Applications de productivité : Analyser les habitudes de travail et le temps de concentration
• Analyses : Comprendre le comportement des utilisateurs et l’engagement dans les applications