-
Notifications
You must be signed in to change notification settings - Fork 1
Best practices and common problems
This is a collection of our own experiences and best practices that might be helpful for others.
When using notifications, be aware that iOS has a hard limit of 64 notifications that can be pre-scheduled. 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). Read Number of scheduled actions for more information.
Please be aware that ESMira comes with no warranties and most of its features were developed with specific study designs in mind and might have not been tested in specific setups. When creating a new study, we recommend to run through the whole study as a participant yourself at least once to make sure everything works as expected. If possible, do that on Android and iOS since features might behave differently (or have bugs, we are not aware of).
It might be helpful to head to the discussion forum and ask how well a specific feature has been tested, what you should look out for, or if there are any previous experiences that might help you. But please make sure to use the search function in case others have already asked the same questions 🙂.
Study settings can be changed after the study has started. In general, that should not create problems in ESMira. But when your study is using schedules (e.g. for notifications), you need to be more careful: When changing the number of questionnaires, the runtime of questionnaires or anything in schedules itself, the mobile ESMira app will reset all schedules and reschedule them (and notify the user). This can lead to a situation where some notifications are skipped on the day of the study update.
If a study is not public but accessible through an access key, this key serves as a password for the study. Removing an existing key results in the following:
- Important: Any participant that joined the study using that access key (or a qr code with that access key) will lose access to the study. They will not be able to upload any new data and will not be able to send messages.
- Any QR code that was generated with that access key will not work anymore.
- Any url to the study that uses that access key will not work anymore.
Keep an eye on incoming data (on a daily basis, if possible) especially on the first days of your study. When you see a sudden drop in filled out questionnaires, make sure that this is not caused by errors or misconfigurations. ESMira has a Summary feature and Server statistics that can help you keep track of your studies. Have a look at Common problems for more information.
To catch problems early, we recommend to participate in your own study on a regular basis. When problems occur, participants often only seek help after several days (or never) and when they do, it sometimes takes a while to realise that the problem is affecting more than one participant. By also participating yourself, you can catch obvious problems while they are happening.
In our own studies, messages are used frequently by participants. Apart from answering questions that might arise, often they are also a good precursor for misconfigurations or other problems. If you get similar questions on a regular basis then your study design might not be clear enough or maybe there are other problems that confuse your participants.
When joining a study (or when schedules are reset), some schedule will be skipped on the first day. This happens when:
- When using a random time of day and the timespan has already started (e.g. a time of day is set to random between 10:00 and 13:00 and the study is joined at 10:30).
- When the time of day is less than one minute away.
This is a common problem that all Android app developers face. It is caused by manufacturers trying to boost the battery life of their device by sabotaging core Android features. Unfortunately the only solution for this problem is to ask participants for their exact model and version and then guide them through specific settings on their phone via messages and screenshots. ESMira is able to detect when notifications are not working properly and then shows a dialog that guides them through the process (using information provided on https://dontkillmyapp.com). But often, participants might need more help, since many settings provided by manufacturers are not very well done. When searching for solutions, a good place to start, is https://dontkillmyapp.com.
The only upside is, that in recent years manufacturers have become much less aggressive with their "app killers" and the trend seems to be to (slowly) stop using those cheaty tactics altogether.
The general approach is rather to save data multiple times then not to save them at all. Following this, the mobile app will upload its data repeatedly until it is absolutely sure all entries were stored without any errors. This can lead to data being sent to the server multiple times, even though they are already stored properly. Common reasons for that are:
- There was a hiccup in the internet connection:
This can sometimes happen.ESMira should be able to tell if an entry was already stored properly and prevent these kind of duplicates. - The server was able to save data properly but ran into another error. Please follow the steps in Data are not saved
First thing you should do, is figuring out why it happened: Check the events log to see if you notice any irregularities. Are there no new entries at all? Then it might be a server issue. If your study uses invitations, do you see a lot of "invitation_missed" events (please be aware that this event is less reliable on iOS)? If they happen with the same model, this might be an issue with a specific model. It could also be caused by a misconfiguration of your study. Check in Availability and runtime and in Edit triggers if everything is set up correctly. You can change the study settings afterwards, but if you want it to affect already existing participants you also have to increase the study version.
If you believe that you found a bug in ESMira, please open an issue and add as much information as possible:
- The JSON of your study, so we can try to reproduce the problem on our test server (But make sure you stripped it of any confidential information).
- Your ESMira app logs (the easiest way is to send an error report and mention the url to your issue in the comment)
- Your server logs (usually found at /var/logs/apache2 or /var/logs/nginx).
The good news first: The ESMira mobile app always saves data locally and tries to automatically upload them until they were delivered successfully to the server. So, if your ESMira server has hiccups, no data should be lost and will be transferred as soon as your server is up and running again.
The easiest first step is filling out the questionnaire yourself using the app. Then check in the Upload-Protocol if your data is actually saved on the server (with a common internet connection, this should not take longer than a minute). If not, head back to the main screen of ESMira and open the error report dialog. Click the button "What is sent?" and scroll down through the logs. One of the more recent logs should be a warning with the headline "Syncing failed". This log should either have a server response telling you the reason why the sync was rejected or have a longer "bare" error message. Former might point you to a reason why the server is misconfigured (for example, access keys for the study might have been changed) and should be able to be resolved through the admin interface. If it is the latter, you will probably need help from IT, because it could mean that it is caused by a server issue. To speed up troubleshooting, look through the error message and see if you can find the phrase "500 Internal Server Error". If yes, ask IT for the server logs from that time (they are usually stored at /var/logs/apache2/ or /var/logs/nginx/). If you think your error is something specific to ESMira, have a look at I found a bug in ESMira