搜尋套件、儲存庫與 APP 分類

套件詳情v2.0.1

usage_stats

查詢 Android 使用統計資訊(設定、事件、使用情況)

Android
近 30 天下載
2360
喜歡數
49
Pub 分數
160

安裝套件

flutter pub add usage_stats

套件介紹

根據套件公開資料產生的選型評估,僅供參考。

usage_stats 套件讓 Flutter 應用程式能夠查詢 Android 使用統計資料,包含應用程式使用時間、設定變更以及使用者互動事件。它提供對系統層級資料的存取,以了解使用者如何與裝置及安裝的應用程式互動,進而獲得使用模式的洞見。此套件專為 Android 設計,利用 Android UsageStatsManager API。對於需要詳細追蹤應用程式與裝置使用情況的分析、生產力工具或數位健康應用程式而言極具價值。

適用情境

  • 應用使用模式的分析
  • 數位健康監控
  • 使用者行為追蹤
  • 設備活動報告
  • 在應用上花費的時間

主要特色

  • 存取 Android UsageStatsManager
  • 即時使用事件收集
  • 支援設定和使用資料
  • 平台特定(僅限 Android)
  • 輕量且直接的整合

適合對象

  • 生產力應用
  • 健康追蹤器
  • 分析工具
  • 專注於 Android 的應用
  • 開發基於使用情況功能的開發者

使用建議

  • 僅限 Android 的平台支援
  • 需要執行時權限
  • 僅限 Android 運作系統
  • 可能需要使用者同意才能存取資料
  • 依賴系統級 Android API

原始 README

以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。

usage_stats

pub package pub points likes license

Query Android usage statistics from Flutter: app usage and events, configuration changes, app standby buckets, on-device storage usage, and per-app network data. The plugin wraps Android's UsageStatsManager, NetworkStatsManager, StorageStatsManager, and PackageManager behind a single UsageStats facade.

This package is Android only. iOS does not expose comparable per-app usage data to third-party apps, so the plugin declares no iOS implementation.

Screenshots

The bundled example app showcases every API:

Per-app foreground usage Usage events with readable types Per-app storage and metadata App standby bucket and self events

Install

Add usage_stats to your pubspec.yaml:

dependencies:
  usage_stats: ^2.0.0

Android setup

The plugin targets API level 23 (Android 6.0) as a minimum. Most queries need the special PACKAGE_USAGE_STATS permission, which the user grants from system settings rather than through a runtime dialog.

Add the permission to your android/app/src/main/AndroidManifest.xml, inside the manifest element:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-permission
        android:name="android.permission.PACKAGE_USAGE_STATS"
        tools:ignore="ProtectedPermissions" />

    <application ...>

Granting the permission

Send the user to the system "Usage access" screen and check whether access has been granted:

import 'package:usage_stats/usage_stats.dart';

// Opens the system Usage Access settings screen (only if not yet granted).
await UsageStats.grantUsagePermission();

// Opens the same screen unconditionally, e.g. for a "Manage access" button.
await UsageStats.openUsageAccessSettings();

// Returns true once the user has enabled access for your app.
bool? granted = await UsageStats.checkUsagePermission();

Querying usage

final endDate = DateTime.now();
final startDate = endDate.subtract(const Duration(days: 1));

// Raw usage events (foreground/background transitions, screen on/off, …).
List<EventUsageInfo> events = await UsageStats.queryEvents(startDate, endDate);

// Per-app foreground usage.
List<UsageInfo> usage = await UsageStats.queryUsageStats(startDate, endDate);

// Per-app usage aggregated by package, keyed by package name.
Map<String, UsageInfo> aggregated =
    await UsageStats.queryAndAggregateUsageStats(startDate, endDate);

// Configuration (locale/orientation/…) statistics.
List<ConfigurationInfo> configs =
    await UsageStats.queryConfiguration(startDate, endDate);

// Aggregated event statistics (Android 9 / API 28+).
List<EventInfo> eventStats =
    await UsageStats.queryEventStats(startDate, endDate);
Interval granularity

queryUsageStats and queryEventStats accept an optional intervalType that maps to UsageStatsManager.INTERVAL_*. It defaults to IntervalType.best.

final monthly = await UsageStats.queryUsageStats(
  startDate,
  endDate,
  intervalType: IntervalType.monthly,
);

Network usage

// Per-app network usage for all apps.
List<NetworkInfo> network = await UsageStats.queryNetworkUsageStats(
  startDate,
  endDate,
  networkType: NetworkType.all, // or NetworkType.wifi / NetworkType.mobile
);

// Network usage for a single package.
NetworkInfo info = await UsageStats.queryNetworkUsageStatsByPackage(
  startDate,
  endDate,
  packageName: 'com.example.app',
);

Network totals are summed across the Wi-Fi and cellular transports. When a VPN is active the platform may attribute traffic to the VPN app as well as the originating app, which can make per-app totals appear higher than expected.

Storage usage

// App, data, and cache bytes for a package (Android 8 / API 26+).
StorageInfo? storage = await UsageStats.queryStorageStats('com.example.app');
print(storage?.totalBytes);

Querying your own package needs no permission; querying other packages requires PACKAGE_USAGE_STATS.

App metadata and icons

// Label, system flag, version, and install times for one package.
AppInfo? app = await UsageStats.getAppInfo('com.example.app');

// Every installed app the caller can see (set includeSystem: false to skip
// system apps).
List<AppInfo> installed =
    await UsageStats.queryInstalledApps(includeSystem: false);

// PNG launcher icon bytes.
Uint8List? icon = await UsageStats.getAppIcon('com.example.app');

On Android 11+ (API 30) package-visibility rules apply. Without a <queries> entry in your manifest, queryInstalledApps returns only visible packages. The plugin deliberately does not request QUERY_ALL_PACKAGES, since it is a Play-policy sensitive permission.

App standby

// This app's standby bucket (no permission required, Android 9 / API 28+).
int? bucket = await UsageStats.getAppStandbyBucket();

// Whether a package is currently idle (Android 6 / API 23+).
bool? idle = await UsageStats.isAppInactive('com.example.app');

// This app's own events without the usage-access prompt (Android 9 / API 28+).
List<EventUsageInfo> ownEvents =
    await UsageStats.queryEventsForSelf(startDate, endDate);

Typed accessors

For backwards compatibility the model fields are returned as strings, mirroring the raw platform values. Every model also exposes typed getters so you do not have to parse them yourself:

final info = usage.first;
info.totalTimeInForegroundMs; // int?  (milliseconds)
info.lastTimeUsedDate;        // DateTime?

events.first.eventTypeDescription; // e.g. 'ACTIVITY_RESUMED'
network.first.rxTotalBytesValue;   // int?

totalTimeInForeground is reported in milliseconds.

API levels and permissions

Method Min API Permission
queryUsageStats, queryEvents, queryConfiguration, queryAndAggregateUsageStats 23 PACKAGE_USAGE_STATS
queryEventStats 28 PACKAGE_USAGE_STATS
queryNetworkUsageStats, queryNetworkUsageStatsByPackage 23 PACKAGE_USAGE_STATS
queryStorageStats 26 own package: none; others: PACKAGE_USAGE_STATS
getAppStandbyBucket, queryEventsForSelf 28 none
isAppInactive 23 PACKAGE_USAGE_STATS for other packages
getAppInfo, queryInstalledApps, getAppIcon 21 none (subject to package visibility)

API-gated methods degrade gracefully on older devices, returning null or an empty list rather than throwing.

Contributing

The Dart code is linted with flutter analyze against flutter_lints. The Android Kotlin sources are checked with detekt and ktlint:

./tool/lint_kotlin.sh

License

MIT

所屬分類

原始碼儲存庫

使用此套件的專案