flutter_mobile_diagnostics #

A Flutter plugin that answers: how healthy is this device right now, and what context should I attach to a support ticket or crash report?

Collect a typed snapshot of device identity plus seven runtime domains (battery, memory, storage, network, Bluetooth, security, performance). Each domain is scored as healthy, warning, critical, or unknown. The full report serializes to JSON for Sentry, Crashlytics, or your backend.

Screenshots #

Example app overview on Android and iOS:

Android	iOS

Features #

• One call, full picture — getFullReport() returns identity + all health domains + overall score.
• Granular getters — fetch only battery, memory, storage, and so on.
• Actionable status — Dart scoring (HealthInterpreter), not raw maps in the public API.
• JSON-ready — every model has toJson(); toJsonReport() is a one-liner for crash SDKs.
• Configurable — thresholds and opt-in security / reachability via DiagnosticsOptions.
• Live updates — watch() polls battery, memory, and network (v1; EventChannel planned later).
• Fail gracefully — missing permissions or APIs become unknown, not a crash.
• Android & iOS — native collectors on both mobile platforms.

This package is not a full APM suite, Bluetooth pairing library, or tamper-proof fraud detector.

Install #

dependencies:
  flutter_mobile_diagnostics: ^0.2.0

flutter pub get

Quick start #

import 'package:flutter_mobile_diagnostics/flutter_mobile_diagnostics.dart';

final diagnostics = MobileDiagnostics();

final report = await diagnostics.getFullReport();

debugPrint('${report.overallStatus}  ${report.overallScore}');
debugPrint('Battery ${report.battery.levelPercent}%');
debugPrint('${report.device.manufacturer} ${report.device.model}');

Attach to a crash or support payload:

final json = await diagnostics.toJsonReport();
// crashReporter.setContext('device_health', json);

API overview #

MobileDiagnostics is cheap to construct. Native work starts on the first method call.

Options #

final report = await diagnostics.getFullReport(
  options: const DiagnosticsOptions(
    includeSecurityChecks: true,
    includeRootJailbreakCheck: false, // advisory; off by default
    includeNetworkReachability: false, // extra latency; off by default
    batteryWarningThresholdPercent: 20,
    batteryCriticalThresholdPercent: 10,
    memoryWarningThresholdPercent: 75,
    memoryCriticalThresholdPercent: 90,
    storageWarningThresholdMb: 500,
    storageCriticalThresholdMb: 100,
    collectionTimeout: Duration(seconds: 5),
  ),
);

Single domain #

final memory = await diagnostics.getMemoryHealth();
final perf = await diagnostics.getPerformanceHealth();

final canRunHeavyWork = memory.status != HealthStatus.critical &&
    perf.thermalState != ThermalState.critical;

Watch battery / network #

final sub = diagnostics
    .watch(domains: DiagnosticsDomain.watchableDefaults)
    .listen((snapshot) {
  final level = snapshot.battery?.levelPercent;
  if (level != null && level < 15) {
    // show low-battery UX
  }
});
// later: await sub.cancel();

Health scoring #

Native code returns raw metrics. Scoring is pure Dart so Android and iOS share the same rules.

Overall status = worst domain (critical > warning > unknown > healthy).

Overall score (0–100) = weighted average: memory 25%, storage 20%, battery 15%, performance 15%, network 10%, security 10%, Bluetooth 5%.

unknown contributes a neutral 50 to the score.

Example JSON #

{
  "device": {
    "manufacturer": "Samsung",
    "model": "SM-G991B",
    "os_name": "Android",
    "os_version": "14",
    "app_version": "1.2.3",
    "is_physical_device": true
  },
  "battery": {
    "level_percent": 78,
    "state": "discharging",
    "status": "healthy"
  },
  "overall_status": "healthy",
  "overall_score": 92.5,
  "collected_at": "2026-08-29T17:14:00.000Z",
  "collection_duration_ms": 145
}

Permissions #

Android #

Merged from the plugin manifest (host apps inherit these):

If Bluetooth permission is denied, Bluetooth health is unauthorized / unknown. The rest of the report still succeeds.

iOS #

Add a usage string if you query Bluetooth adapter state (the example app already does):

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth adapter state is used only for device health diagnostics. The app does not scan or pair accessories.</string>

Platform notes #

Supported on Android and iOS only. Availability varies by OS version; missing APIs are omitted or marked unknown.

• Android / iOS — battery, memory, storage, network, Bluetooth adapter state, security heuristics, thermal / performance signals.
• Root / jailbreak checks are heuristic and opt-in. They are not forensic or anti-tamper guarantees.

Example app #

The example/ project is a full demo:

1. Overview — overall score, domain grid, and live monitor
2. Domain detail — per-getter drill-down
3. Live — watch()
4. Report — toJsonReport()
5. Settings — DiagnosticsOptions toggles

cd example
flutter run

Testing #

flutter test --coverage
cd example && flutter test --coverage

Swap the platform in unit tests:

FlutterMobileDiagnosticsPlatform.instance = MyFakePlatform();
MobileDiagnostics.clearCache();

Further reading #

• doc/ANALYSIS_AND_DESIGN.md — requirements, landscape, domain mapping
• doc/DESIGN.md — architecture, models, native collectors, scoring

License #

BSD 3-Clause. See LICENSE.