screen_time 0.3.0

The Screen Time is a set of tools that lets developers create apps that help users manage their device usage and time. It also allows parents to supervise their children's device use.

Screen Time Plugin

A Flutter plugin for monitoring app usage in real-time on Android devices. This plugin provides detailed information about the currently active application and app usage statistics.

Features

• Get detailed information about the currently active app
• Monitor app usage in real-time
• Configure monitoring intervals and lookback times
• Access app usage statistics

Installation

Add the plugin to your pubspec.yaml file:

dependencies:
  screen_time: ^1.0.0

Setup

Android

1. Permission Information

The core permissions required by this plugin are already declared in the plugin's AndroidManifest.xml:

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

You don't need to add these permissions to your app's AndroidManifest.xml as they're automatically merged during the build process.

2. Implement the Accessibility Service

To monitor app usage in real-time, you need to implement an accessibility service in your app. Follow these steps:

a. Create accessibility service configuration

Create a file at android/app/src/main/res/xml/accessibility_service_config.xml with the following content:

<?xml version="1.0" encoding="utf-8"?>
<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
    android:description="@string/accessibility_service_description"
    android:accessibilityEventTypes="typeWindowStateChanged|typeWindowContentChanged"
    android:accessibilityFeedbackType="feedbackGeneric"
    android:notificationTimeout="50"
    android:canRetrieveWindowContent="true"
    android:canPerformGestures="false" />

b. Add service description

Add the following string to android/app/src/main/res/values/strings.xml:

<string name="accessibility_service_description">This service monitors app usage in real-time and provides detailed information about the apps you use.</string>

c. Register the service

Add the following service declaration to your app's AndroidManifest.xml within the <application> tag:

<service
    android:name="com.solusibejo.screen_time.service.AppMonitoringService"
    android:label="App Monitoring Service"
    android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"
    android:exported="false">
    <intent-filter>
        <action android:name="android.accessibilityservice.AccessibilityService" />
    </intent-filter>
    <meta-data
        android:name="android.accessibilityservice"
        android:resource="@xml/accessibility_service_config" />
</service>

Usage

Request Permissions

Before using the plugin, request the necessary permissions:

final ScreenTime screenTime = ScreenTime();
final permissionStatus = await screenTime.requestPermission();

if (permissionStatus.status) {
  // Permission granted, proceed with usage
} else {
  // Handle permission denied
}

Open Accessibility Settings

To enable the accessibility service, guide the user to the system accessibility settings:

await screenTime.openAccessibilitySettings();

Check if Service is Enabled

final isEnabled = await screenTime.isAppMonitoringServiceEnabled();

Configure the Service

You can configure the monitoring interval and lookback time:

await screenTime.configureAppMonitoringService(
  interval: UsageInterval.daily,
  lookbackTimeMs: 10000, // 10 seconds
);

Monitor App Usage

final result = await screenTime.monitoringAppUsage(
  startHour: 0,
  startMinute: 0,
  endHour: 23,
  endMinute: 59,
  usageInterval: UsageInterval.daily,
  lookbackTimeMs: 10000,
);

if (result.status) {
  // Access current foreground app information
  final currentApp = result.currentForegroundApp;
  print('Current app: ${currentApp?["appName"]}');
}

Get App Usage Data

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

final List<AppUsage> usageData = await screenTime.appUsageData(
  startTime: yesterday,
  endTime: now,
  usageInterval: UsageInterval.daily,
);

for (final app in usageData) {
  print('${app.appName}: ${app.usageTime} ms');
}

Example

See the example directory for a complete sample app demonstrating how to use this plugin.

Customization

You can customize the accessibility service by modifying the accessibility_service_config.xml file. For more advanced customization, refer to the Android Accessibility Service documentation.

License

This project is licensed under the MIT License - see the LICENSE file for details.