Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando los siguientes comandos y sigue las instrucciones específicas para cada plataforma a continuación:

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

Importar

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

Inicio rápido

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

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

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

Errores comunes

• Sync nativo: ejecutar npx cap sync tras actualizar los plugins.
• Fuente de verdad: confiar src/definitions.ts en el repo de GitHub.

Resumen de API

queryAndAggregateUsageStats

Consulta y agrega estadísticas de uso en el rango de tiempo indicado.

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

Comprueba si el permiso de estadísticas de uso está concedido.

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

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

openUsageStatsSettings

Abre la pantalla de ajustes de estadísticas de uso. Esto abrirá la pantalla de ajustes de estadísticas de uso, permitiendo al usuario conceder el permiso de estadísticas de uso. Esto siempre abrirá la pantalla de ajustes, incluso si el permiso ya ha sido concedido.

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

await CapacitorUsageStatsManager.openUsageStatsSettings();

queryAllPackages

Consulta todos los paquetes instalados en el dispositivo. Requiere el permiso 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}`);
});

Referencia de tipos

UsageStatsOptions

Opciones para consultar estadísticas de uso.

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

Estadísticas de uso de una app de 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

Resultado de la comprobación de permisos de usage stats.

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

PackageInfo

Representa información básica sobre un paquete instalado.

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

Fuente de verdad

Esta página se genera a partir del src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en el upstream.

Continúa desde Primeros pasos

Si estás usando Primeros pasos para planificar el dashboard y las operaciones de API, conéctalo con Uso de @capgo/capacitor-android-usagestatsmanager para la capacidad nativa en el uso de @capgo/capacitor-android-usagestatsmanager, Resumen de API para el detalle de implementación en Resumen de API Overview, Introducción para el detalle de implementación en Introducción, Claves de API para el detalle de implementación en Claves de API, y Dispositivos para el detalle de implementación en Dispositivos.