Screen State

Reference
1

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:

  • Record Time: The time when the previous state of the device started. Internally stored as record_time.
  • 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.

[!note]
For analysis, treat state and lock_state independently. Do not assume locked/unlocked are replacements for true/false.

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 screen state 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 Display or Lock States

When exporting Screen State data, you may see consecutive entries with the same state (e.g., two false values) or the same lock_state (e.g., two locked 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 state again, which may match the previously recorded state.

For the purpose of data analysis, you can simply discard consecutive records with duplicate state or lock_state and only use the first record from those duplicates.