Skip to main content

Digital Footprint

Screen State​

Supported on Android & iOS.

This data source records the time that the device's display turns on/off and the time that 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.

The data source does not record the content of the screen or the reason for changes. It only captures the change and timing information.

Each screen state record includes the following:

Record Time: The time the previous state of the device had started. Internally stored as record_time.

End Time: The time the previous state of the device had ended. Internally stored as end_time.

State: Whether the display turned on or off. Internally stored as state. This is true if the display was on and false if the display was off. If the display state hasn't changed, this will be null.

Lock State: Whether the device was locked or unlocked. Internally stored as lock_state. This is locked if the device was locked and unlocked if the device was unlocked. If the lock state hasn't changed, this will be null.

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) and the device was on until 1606939060036 (2020-12-02 14:57:40.036-05:00). 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.

App Usage​

Supported in Android.

This data source records how often participants are using which app. The captured data only includes the name of the app and the aggregate amount of time it was used over a certain period. It does not include any content of the application.

Each app usage record includes the following:

App Name: The unique code name of the app used, for example, com.ethica.logger for Avicenna or com.facebook.kanata for Facebook. Internally stored as app_name.

Start Time: The beginning of the time period over which this report was collected. Note that this does NOT refer to the time the application was started. Internally stored as start_time.

End Time: The end of the time period over which this report was collected. Note that this does NOT refer to the time the application was closed. Internally stored as end_time.

Last Used: Last time the application was used (the time the app was closed), in the time window specified by the start_time and the end_time. Internally stored as last_used.

Foreground Time (MS): The amount of time, in milliseconds, that the application was in the foreground during the time window specified by the start_time and the end_time. An app is considered foreground if one of its screens is the currently active screen and the user is looking at it (i.e. the screen is on) or interacting with it. Internally stored as foreground_time_ms.

As an example, if a record is shown as follow:

{
  "study_id": 1,
  "user_id": 1,
  "device_id": "b66448991d665fb3",
  "app_name": "com.google.android.youtube",
  "record_time": 1550942264787,
  "start_time": "May 9th 2018, 09:30:45.537+0000",
  "end_time": "May 10th 2018, 09:30:45.536+0000",
  "last_used": "May 10th 2018, 09:03:54.098+0000",
  "foreground_time_ms": 12379944
}

It means during the 24 hour period from May 9th 2018, 09:30:45.537+0000 to May 10th 2018, 09:30:45.536+0000, the participant was using YouTube (com.google.android.youtube) for approximately 206 minutes (12,379,944 milliseconds).

Configuration in Android​

Monitoring app usage statistics has been integrated into the core functionalities of the Avicenna app.

In studies where app usage data monitoring is required, Avicenna handles this internally without the need for any additional installations. Upon registration, participants will receive a notification through the Avicenna app to grant permission to access app usage data. This notification provides participants with an easy way to navigate to the required settings and grant permission.

By eliminating the need for a separate extension app, we have streamlined the process, making it more straightforward for participants. Now, they need to download and install the Avicenna app from the Google Play Store, provide the necessary permissions, and they're all set.

Alternatively, participants can be instructed to follow the steps below to grant permission via device settings, before they receive the notification from the Avicenna app:

  1. Open Android's Settings.
  2. Click on Security.
  3. Scroll down to find and then select Apps with access to usage data.
  4. From the list of applications shown, select Avicenna.
  5. Switch Allow usage tracking to On.

This will provide the required permission for Avicenna to access statistics on app usage.

Android Apps with 0 ms Usage​

This data source captures any app that is running on the participant's Android device, even if they don't interact with that app directly. An example is Google Mobile Services which usually runs behind the scenes and performs support tasks. But as it's running, the collected data will include references to it (com.google.android.gms), indicating that it's been used for 0 milliseconds. If you are focused on the apps the participant has directly interacted with them, you can exclude the results with 0 ms foreground time.