Screen State

Supported on Android & iOS.

This data source records the time that the smartphone's screen turns on or off. It does not record the content of the screen or for what reason it was turned on or off. It only captures whether it was turned on or off, and the time of the event.

Each screen state record includes the following:

record_time:
The time the new state of the phone has started. Internally stored as record_time.

end_time:
The time the new state of the phone has ended. Internally stored as end_time.

State:
Whether the screen turned on or off. Internally stored as 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
}

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

App Usage

Supported in Android.

This data source records how often participants are using which app. When a study chooses to monitor app usage data source, all participants who use an Android device will be notified to download and install an extension app on their smartphone which provides this functionality. 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 Ethica 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 is not part of the Ethica app by default. Instead, this functionality is offered through an extension app, Ethica App Usage Stream, which also can be downloaded from Google Play Store. This separation allows improving the data security and controls the risks associated with accessing such sensitive data.

If a given study chooses to monitor this data source, shortly after the registration Ethica detects the App Usage extension is not installed and notifies the participant to install the application. Participants can wait for the notification to be shown in the Ethica app and then click on it to download the application. Alternatively, they can be instructed to download and install Ethica App Usage Stream directly from Google Play, after installing Ethica app. This way they will not receive the above-mentioned notification anymore.

When Ethica App Usage Stream is installed, participants still have to explicitly instruct their Android device to allow Ethica App Usage Stream to access their app usage data. If this permission is not granted, participants will receive a notification through the Ethica app. This notification provides participants with an easy way to change the required settings and grant the permission.

Alternatively, participants can be instructed to follow the steps below to grant the permission via phone's settings, before they receive the notification from the Ethica 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 App Usage Statistics Stream.
  5. Switch Allow usage tracking to On

This will provide the required permission for Ethica 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 phone, 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.