Summary
This feature provides users with a detailed dashboard to monitor their digital habits through two primary metrics: Phone Usage (how much time is spent on the device) and Unlocks (how many times the device is opened). It visualizes this data using a calendar heatmap to show trends over time and provides a ranked list of apps contributing to these metrics. It also handles historical data for apps that have since been uninstalled, ensuring usage statistics remain accurate even after an app is removed.How It Works
The feature works by aggregating raw system events (screen time and unlock events) and combining them with app details (names and icons) to present a user-friendly report.Data Collection & Aggregation
When the user opens the Phone Usage or Unlocks screen, the ViewModel requests data from the repository. It fetches two types of information:
- Raw Statistics: The time spent or number of unlocks per day, stored in the local database.
- App Metadata: The names and icons of currently installed apps.
Period Calculation
The user can switch between Daily, Weekly, and Monthly views.
- Daily: Shows the exact total for the selected date.
- Weekly/Monthly: Calculates the average usage or unlocks per day over that period to help the user understand their baseline habits.
Categorizing Apps
The system processes the list of apps to handle them correctly:
- Installed Apps: Matched with their current icons and names.
- Removed Apps: If the database has usage data for an app that is no longer installed, it is grouped into a “Removed Apps” category so the total statistics remain accurate without cluttering the main list.
Visualizing the Heatmap
The ViewModel generates a “Heatmap” dataset. This assigns an intensity level to every day in the calendar based on how high the usage was compared to other days. This allows the user to visually spot “heavy usage” days at a glance.
Data Stored
The feature processes and displays the following data structures for each app in the list:| Field | Type | Description |
|---|---|---|
| packageName | String | The unique system identifier for the app (e.g., com.example.app) |
| appName | String | The human-readable name of the app |
| usageTimeMillis | Long | (Usage Screen) Total time the app was used in milliseconds |
| openCount | Integer | (Unlocks Screen) Number of times the app was opened |
| isInstalled | Boolean | Indicates if the app is currently on the device |
| limitInfo | Object | Details about any active time limits set for this app |
Key Components
PhoneUsageScreen
Displays the total screen time, the calendar heatmap, and the list of apps sorted by duration of use.
UnlocksScreen
Displays the total count of device unlocks, the heatmap, and a list of apps sorted by how frequently they are opened.
ViewModels
PhoneUsageViewModel and UnlocksViewModel handle the math for averages, merge installed vs. removed app data, and manage the date selection logic.Heatmap Component
A visual component that colors calendar days based on intensity (darker colors = higher usage/unlocks).