# Screen State

**URL:** <https://forum.avicennaresearch.com/t/screen-state/1257>\
**Category:** Reference\
**Created:** [June 16, 2025, 9:19am UTC](https://forum.avicennaresearch.com/t/screen-state/1257 "2025-06-16T09:19:06Z")\
**Posts on this page:** 1\
**Showing post:** 1

<div class="post-metadata">

**Author:** ![mojtaba](https://forum.avicennaresearch.com/letter_avatar_proxy/v4/letter/m/e56c9b/32.png) [@mojtaba](https://forum.avicennaresearch.com/u/mojtaba)\
**Post date:** [June 16, 2025, 9:19am UTC](https://forum.avicennaresearch.com/t/screen-state/1257/1 "2025-06-16T09:19:06Z")

</div>

> 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](https://forum.avicennaresearch.com/t/data-sources/1266#p-2893-common-data-fields-4), 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:

```json
{
  "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](https://forum.avicennaresearch.com/t/data-sources/1266#p-2893-adding-data-sources-1).

## Data Collection Behavior

See [Data Collection Behavior of Avicenna](https://forum.avicennaresearch.com/t/data-sources/1266#p-2893-data-collection-behavior-of-avicenna-5).

## Monitoring and Exporting Screen State Data

You can monitor and export screen state data using either [the Data Export page](https://forum.avicennaresearch.com/t/raw-data/1241/1#p-2868-exporting-raw-data-1) or [Kibana](https://forum.avicennaresearch.com/t/kibana-basics/1289/1#p-2916-avicenna-kibana-integration-1).

## 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.

---

_[View the full topic](https://forum.avicennaresearch.com/t/screen-state/1257)._