Smartphone app overview
The smartphone app is not bound to a specific server. This makes it easier for researchers because they do not need a developer account and have to maintain their own separate version of ESMira. You can find ESMira in the App store here:
When opening ESMira for the first time, a welcome screen will guide the participant through the process of finding their study. Later on, they can join other studies by selecting the "+" button at the top right of the starting dashboard.
Note: When the app is enlisted to multiple studies the "+" button at the top right is replaced by a "switch" button which opens a dropdown menu enabling users to switch between studies. This menu als includes the option to "join a new study"
Participants can either scan a QR-code that has been created by the web interface (see Publication, Links & QR code) or provide the study details manually. When not using a QR code, a server can be selected from a list or typed in manually (by selecting "Enter manually").
The main screen opens when the app was opened and is already enlisted to a study.
Note: Depending on which features are enabled for the current study, some buttons might be hidden in the dashboard.
This screen lists all questionnaires that can be filled out at the moment. A button to the right of the "questionnaire" header opens a dropdown menu wich leads to a list of studies that are set up but are not visible at the moment.
This gives access to general information about the study, like the description and informed consent (which is also shown when joining the study), the user id used for this study (which can be copied to the clipboard via button) and some general statistics (e.g., number of filled out questionnaires or join date to the study)
For each study there are public and individual statistics available (if set up, see Create Charts). Individual statistics are calculated only from collected data on the phone and are only available inside the ESMira app.
This screen will show the reward code that can be used to prove that a participant os eligible for a reward. The conditions that must be fulfilled in order to receive a reward code, can be set in the admin panel (see Reward system for more information)
Here, participants can send messages to the researcher and view messages that were sent to them (see Anonymous chat messages).
When enabled, participants can change the schedules of their studies (this must be enabled in the admin panel in Edit triggers - which it is by default). Each time a participant changes their schedule a "schedule_changed" event is sent to the server (if enabled)
The upload protocol gives an overview of all the times data been uploaded to the server. It also displays the upload state of data. Data that failed to upload with a critical error can be manually deleted using the bin icon.
Leaving the study removes all questionnaires and pending notifications for the study. All study data (like messages, statistics or questionnaire data). If there is questionnaire data that has not been uploaded yet, the app will still try to do so.
Rejoining is only possible when the study is still available on the server (and is not disabled) otherwise it will fail with an error saying that no study is available. The app will try to download the study details from the server again and lead the user through the joining process again. After rejoining the study will start from the beginning again (and the join date will be updated as well).
Deleting a study is only possible after the study as been left (or was finished automatically). This will delete all data about this study that are saved on the phone. Before the deletion is commenced, the app checks if all study data has been successfully uploaded. If not it will fail with a warning.
There is a settings button on the top right of the dashboard. This button opens a dropdown menu with the options to send an error report ("Send error report"), getting help if notifications are not working on the smartphone ("Notifications are not working?"), manually check if there are updates for studies (which should be needed since it is done automatically) or display further information about the project ("About ESMira").
Most of the crucial code is shared between the Android and iOS app but there are some notable differences:
All timed actions (either events with a timeout or schedules) are very limited in iOS which leads to some restrictions:
In Android, notifications and other actions can be executed at specific times. In iOS, only notifications are executed at the correct time. Other actions (e.g. sending a message to the participant) are executed only after the participant opens the ESMira app or taps the notification. Because of this limitation, the iOS app has an additional actions_executed event which marks when the participant has reacted to the notification. Additionally, the events "invitation", "message" or "reminder" are not triggered in iOS. Also, keep in mind that "passive" events (e.g. "invitation_missed") are not recorded when the event happened but when the participan opens the app (or the background service is run, which should happen twice a day).
Only a limited amount of actions can be appointed in iOS. For that reason, ESMira will try to never schedule more than 55 notifications at the same time (this includes each time of day in a schedule, each random notification when time of day are randomized and additional reminders that are set per notification). To overcome this restriction, only schedules for the next 4 repetitions (or less if a study uses a lot of notifications) for each time of day are appointed at the same time. Everytime the participant opens ESMira, the next days are refreshed and new actions are appointed if needed. Because of that, schedules will eventually stop if ESMira was not used for a while (there is a background service making sure notifications keep being scheduled. But it is not guaranteed that iOS is allowing this service to run indefinitely.
Example: A study has one schedule with 2 times of day. One of the is random with a frequency of 3. The schedule is set to have 2 reminder. That would mean the app will schedule 48 notifications: The study has a total of 4 times of day (one static and one random with 3 times of day). Each of them has 2 reminder (so in total 8 reminder). So each day, ESMira has to schedule 12 notifications. ESMira will pre-schedule the next 4 repetitions (if the schedule is set to repeat every one day, this would mean 4 days), leading to 48 notifications in total.
In theory, the background behavior of ESMira is very similar in iOS and Android. In practice, iOS tends to limit background services quite quickly which means that updating and syncing studies will only happen reliably when the app is started (or running).
In iOS, it is not possible to remove notifications via app after they have been created.
All data collected by a study is stored on the phone. ESMira tries to upload new data immediately over a secured connection (HTTPS) and, if failed, retries every 3 hours. No data will not be removed from the phone until the study is completed, or the participant deletes the ESMira app.
ESMira checks for messages, updates and uploads unsynced datasets every time the app is started. Additionally:
- Messages and study updates are checked in the background every 12 hours.
- After a questionnaire was filled out, its dataset is immediately uploaded to the study server. If the upload failed (e.g. because the phone has no access to the internet, or the server responds with an error), ESMira will try again in the background after 3 hours (this will be repeated until the upload succeeds). Additionally, failed uploads will be synced whenever ESMira is started.
- for iOS: ESMira tries every 12 hours to update the number of appointed schedules (which are only appointed for the next 4 repetitions, see Number of scheduled actions)
Note: The actual times of background processes can vary greatly, depending on model, manufacturer and battery saving settings of the phone. Some vendors even disallow background processes in general, and others use a "smart decision system" (e.g. Huawei, iOS) that only allows background processes when the app was "recently" used and is opened "often enough" (this is decided by internal algorithms that are not known to the public).
In most cases this is caused by specific phone models. Read Notifications are not working for some participants for more information.
Internet: In order to download studies and upload data, ESMira needs access to the internet.
Notifications If a study uses notifications, ESMira needs permission to do so. This permission will be checked before being able to join the study.
Camera: The camera is used to scan QR codes when joining a study.
Vibrate: ESMira notifications use sound and vibrations.
Timed notifications need to be rescheduled when the phone was restarted. In order to do that, ESMira needs to be able to determine when the phone was booted up again.
Huawei has its own settings for Battery savings that will close apps without any warning making them unable to issue notifications anymore. To keep notifications working, ESMira tells the participant to add an exception for ESMira. This permission is needed to automatically open the respective settings.
Oppo has its own settings for Battery savings that will close apps without any warning making them unable to issue notifications anymore. To keep notifications working, ESMira tells the participant to add an exception for ESMira. This permission is needed to automatically open the respective settings.
Used for the item App usage tracking
Used for the item Record audio
Used for the item List of bluetooth devices
Used for the items "List of bluetooth devices" and "Compass item"
Used for the item Record audio
Used for the item List of bluetooth devices
Used for the items "List of bluetooth devices" and "Compass item"