Supported on Android & iOS.
This data source records the time when the participant’s device display turns on/off, and the time when the device gets locked/unlocked. For each change in either the display state (on/off) or the lock state (locked/unlocked), a new record is created containing the previous state of whichever changed.
[!note]
The data source does not record the content of the screen or the reason for changes. It only captures the change and timing information.
Use Cases
- Mental health research: Analyzing device unlock and screen-on patterns to understand the relationship between screen time, daily routines, and mental health outcomes such as stress, anxiety, or mood changes
- Physical activity and sedentary behavior: Measuring periods of inactivity by combining screen-off/locked states with accelerometer data to study sedentary time and its health consequences
- Sleep research: Investigating how screen-off or locked periods correspond to sleep duration, quality, and circadian patterns
- Behavioral science: Gaining insights into participants’ daily routines, device engagement habits, and timing of interactions to understand cognitive load, multitasking, and lifestyle behaviors
Data Structure
Besides the common data fields, each record contains:
End Time: The time when the previous state of the device ended. Internally stored as end_time.
State: Whether the display was turned on or off. This is true if the display was on and false if the display was off. If the display state has not changed, this will be null. Internally stored as state.
Lock State: Whether the device was locked or unlocked. This is locked if the device was locked and unlocked if the device was unlocked. If the lock state has not changed, this will be null. Internally stored as lock_state.
Interpretation
A given record of this data source looks like the following:
{
"study_id": 1,
"user_id": 2,
"device_id": "2bae23410b7063ec",
"record_time": 1606939056984,
"end_time": 1606939060036,
"state": true,
"lock_state": null
}
This means user ID 2 on device ID 2bae23410b7063ec, turned on the device (state is true) at 1606939056984 (2020-12-02 14:57:36.984-05:00 UTC) and the device was on until 1606939060036 (2020-12-02 14:57:40.036-05:00 UTC). The lock_state is null because this record represents a change in the display state only and each record captures a change in either the display state or lock state, but not both.
Adding Screen State As a Data Source
See Adding Data Sources.
Data Collection Behavior
See Data Collection Behavior of Avicenna
Monitoring and Exporting Screen State Data
You can monitor and export environmental sensors data using either the Data Export page or Kibana.
Screen State Data Source in the Participant App
Participants do not need to do anything (e.g., grant permissions) for this data source, and the data collection will start immediately.
Troubleshooting
Consecutive Records with Duplicate State
When exporting Screen State data, you may see consecutive entries with the same State (e.g., two “False” values). This occurs due to app lifecycle events in mobile operating systems.
Sometimes, the Avicenna app is terminated and restarted during data collection. Mobile operating systems may kill background apps to conserve resources, then restart them later. When Avicenna restarts, it records the current screen state again, which may match the previously recorded state.
For the purpose of data analysis, you can simply discard consecutive records with duplicate states and only use the first reported state.
Consecutive Records with Duplicate Lock State
Similar to the display state, you may see consecutive entries with the same lock_state (e.g., two “locked” values). This can occur when the Avicenna app is terminated and restarted during data collection. For analysis, you can discard consecutive duplicate lock states and keep only the first occurrence.
Screen State vs. Lock State
Screen State tracks two separate signals, which do not overlap:
state(true/false) indicates whether the screen display is on or off.lock_state(locked/unlocked) indicates the device lock status.
Only one of these fields appears per event, depending on what changed. For analysis, treat each field independently and do not assume locked / unlocked are replacements for true / false.
Missing Screen State Records
For more details on troubleshooting missing Screen State records, see Data Sources – Troubleshooting.