-
Notifications
You must be signed in to change notification settings - Fork 6
FAQs and Beiwe Troubleshooting
Surveys are very easy to set up in the Beiwe backend. Beiwe supports five question types: Informational Text, Slider, Radio Button, Checkbox, Free Response (Numeric, single-line text, multi-line text). Beiwe also supports survey branching. The calendar for survey delivery is very basic – day/time is configurable for a survey via a pop-up time picker. Three other configurable items are available for surveys:
- Show survey immediately after registration.
- Randomize which questions are displayed each time the participant takes a survey. This also randomizes the order in which the questions are displayed. It also causes the survey to ignore all question display logic so that all questions have an equal chance of appearing. How many questions are displayed of the total available questions is configurable.
- Randomize without replacement, i.e., on each survey, only display questions that haven't appeared yet on a previous survey, until all questions have appeared in a survey, and then start over Note: Survey branching is not compatible with Beiwe's survey RANDOMIZE feature. Survey branching will be disabled if the RANDOMIZE option is enabled.
Sometimes Android saves the .apk file such that it can't be accessed on installation. To fix this access the file (beiwe.apk) directly from the phone's MY FILES folder if the application won't install from the "Downloads" folder.
My Files is found in different locations depending on phone model, here are some of the most common directions:
- Apps --> My Files --> All Files --> Downloads
- Apps --> Samsung --> My Files --> Download History
- My Files --> Installation files (APK) --> Beiwe
If there's no data from an Android phone go through the following steps with the user:
- Have they been on Wi-Fi during the specified time period? If they haven't, then Beiwe is unable to upload the data and the data is likely still on the phone.
- Have they allowed Beiwe to access their location as a "permission?" This is under Settings --> Device --> Applications --> Application Manager --> Beiwe and then scroll down to see Permissions. Location must be accessible for Beiwe to function properly.
- Have the user check Beiwe's information in the Application Manager (under Settings --> Device --> Applications --> Application manager --> Beiwe) and check the storage on that screen. If the amount of Storage used is very high, that might indicate that the phone is failing to upload data files. The user should connect to a reliable Wi-Fi server for an hour or longer.
If there's no data from an iOS phone go through the following steps with the user:
- Have they been on Wi-Fi during the specified time period? If they haven't, then Beiwe is unable to upload the data and the data is likely still on the phone.
- Have they allowed Beiwe to access their location as a "permission?" This is under settings -> Privacy -> Location Services -> Beiwe, make sure it says "Always." Location must "Always" be accessible for Beiwe to function properly.
- The user should connect to a reliable Wi-Fi server for an hour or longer.
Check Settings --> Application Manager --> Beiwe and ensure notifications are enabled. Notifications must be turned on for Beiwe and are required for the survey to be present. The user must click on the actual notification to access the survey. Turning on Do Not Disturb is another form of disabling notifications.
Notifications are likely turned off. Check Settings --> Notifications --> Beiwe and ensure that notifications are enabled. For Beiwe iOS, notifications are not required to take surveys. The user can simply login to Beiwe and the surveys should be available.
- Ask patients to uninstall (Android) or delete (iOS) the Beiwe app from their phone. It will not affect data already collected by the Beiwe backend, but will end the data collection from the phone. (For Android use settings>apps>app manager>beiwe>uninstall.) Uninstalling/deleting Beiwe will delete any remaining data on the phone, but that should be ok as long as the user has had a good WiFi connection at the end of the study allowing Beiwe to uploaded their data. We sometimes suggest the phone be connected to WiFi for 24 hours if the user has had any issues with their data uploading.
- From the Beiwe backend, use the "unregister smartphone" button for each patient id to make sure you stop collecting data as your various patient IDs wrap up their study.
- Some collaborators ask for feedback on the app/study. Here's one such questionnaire that was used: "We would appreciate any feedback about how you found participating in the month-long study. Would you recommend it to other people? Were there ways we could make the experience better? How easy or hard was it to use the app?" Please share any such feedback from users if you request it!
How do we avoid user-errors with the password, or during registration when entering the temporary/new/confirm password?
Have your study participants choose a password that they will remember and one that doesn't use any characters near the back key or the space bar as these commonly cause trouble on the small keyboards.
If a study participant changes phones, or if they need to uninstall/reinstall Beiwe on the same phone, should they use the same Patient ID (PID) or should we assign them a new one?
Study participants can re-enroll with the same PID. However, from the Beiwe backend you must first use the "Un-Register Smartphone" button next to the appropriate Patient ID, so that Beiwe doesn't return an error "PID already in use". When re-registering with the existing PID, the study participant then must enter their own/existing password three times – in the temporary, new, and confirm password fields. If there's a problem with the password, it's also an option to use the "reset password" button to receive a new temporary password.
If the user is unenrolling/re-enrolling on the same Android phone, we suggest using extra caution to make sure the app is fully removed before re-enrolling. To do this, from the phone's Setting button, choose Applications then Application Manager then choose Beiwe. You will see two buttons "force stop" and "uninstall". "Force stop" seems to clean things up best. Press that first before pressing the uninstall. Then restart the phone before re-installing the Beiwe app.
Recap: Settings --> Applications --> Application Manager --> Beiwe --> Force stop --> Uninstall --> Restart the phone.
What is the error "Sorry, either your Study URL. your User ID, or your Temporary password is incorrect." when registering a study participant?
This indicates a typo in one of the fields -- a typical situation on smartphones.
Other common problems are:
- When re-registering a study participant in a study due to a new phone or to change the passive data settings on their phone, when they enter their Patient/User ID (PID), Android phones sometimes remember the PID and offers it in the spell-check area. If they choose the PID, an extra space is often appended at the end of the PID which then needs to be removed.
- When re-enrolling in a study, since the study participant is entering their current password three times (in the temporary, new, and confirm password fields), just double check as a fail safe, that all three entries are the same length when finished (they just show up as dashes). This is an indication that the password was typed correctly all three times.
The Identifiers file is created when a Beiwe study participant is registered to a study. It contains information for troubleshooting -- what kind of phone, operating system, version of Beiwe installed, registration date/time, etc. The identifiers file typically appears just once unless Beiwe is uninstalled/reinstalled and the study participant is re-enrolled or if the Beiwe participant gets a new phone during the study and enrolls in the study from the new phone. Download the file from the data download tab by entering tge date of installation, or before, and choose the patientID from the patients window and identifiers from data types. Note the phone model recorded for iOS users is hardware based. The iphone wiki for mapping "model" in the identifiers file to which iphone a user has is" https://www.theiphonewiki.com/wiki/Models (The model number of a device is located in the Settings app on the "General -> About" screen under "Model".)
This is the "catch all" error. It's usually a sign that you put your Access or Security key in wrong or that Beiwe is having a network problem. If the problem persists, try resetting your Access and Security Keys.
The mano library lets you write applications that interact with the Beiwe Research Platform. You can request lists of studies, users, device settings, and download files (with or without encryption). See Using-mano and the mano library main page for instructions.
We recommend downloading 1GB of data or less at a time. If your computer times out or the download doesn't complete, try downloading less data. Note, while the amount of data collected depends on your study settings, the typical Onnela Lab study settings generates approximately 1GB of raw data per subject-month.
If Beiwe sends a participant a survey but the person doesn’t respond, how can we find the time the survey was sent?
The iOS and Android Beiwe apps handle this information differently.
Beiwe iOS reports this in the Survey Timings file. The file includes the UTC time and the event column there reports “notified”, “present”, “unpresent”, “submit” or “expired”. If you send a survey every Monday at 9am, for example, it will show this as “notified” at 9am Monday (or whenever it’s delivered). If the subject never takes the survey, the following Monday at 9am it will post an “expired” event which will then be followed by the current Monday survey with a new “notified”. Once the participant takes the survey, the event column reports “present” for each question in the survey and then “unpresent” when the participant moves on to the next question. Finally, the event column reports “submitted” once a survey is submitted.
On the other hand, the survey timings file for an Android user reports when a survey is opened by the participant:
1.53E+12 2018-05-31T17:25:53.397 Survey first rendered and displayed to user zOV1tjt9EaaWForrnTHMnmhR
However, when the Android app displays a survey notification on the phone (ie 9am Monday if on the same study), it doesn't log that event in a Survey Timings file. Instead, it logs that event to the app_log file. It's not very human-readable, but when the app showed a notification for a survey with the ID string EWQckZvokbnp63UJHHfhzhGT, it also wrote the following line to the app_log file:
Received Broadcast: Intent { act=EWQckZvokbnp63UJHHfhzhGT flg=0x14 launchParam=MultiScreenLaunchParams { mDisplayId=0 mFlags=0 } bqHint=1 (has extras) }
A list of Beiwe summary statistics is here: https://github.com/onnela-lab/beiwe/wiki/Summary-Statistics. The available code for summary stats is here: https://github.com/onnela-lab/Beiwe-Analysis.
As an example, the following link is to the primary GPS summary script.
This script takes the raw downloaded GPS data from the Beiwe portal site, imputes missing location information, and then computes daily summary statistics. It is well commented, so this is a good place to start.
If you have additional questions that aren't addressed here, please email Onnela Lab Research Coordinator, Kenzie Carlson at [email protected]. When emailing please provide the following information: phone type and brand, operating system type and number, GPS setting on phone, Wi-Fi setting on phone, notifications setting on phone, patient ID and study name.
We saw this when a study was configured incorrectly. On the Beiwe backend, the wifi data stream was mistakenly set to a frequency of 0 seconds, causing the device to generate literally hundreds of thousands of wifi log files. It looks like the Android app somehow lost its encryption key (maybe something broke during installation), and it keeps trying to write data, crashing, restarting, trying to write data, and crashing again.
Fix the study in the backend (the default frequency for collecting wifi logs, for instance, is every 900 seconds). Ask any enrolled study participants to uninstall and reinstall their apps and re-register since the survey settings are set permanently when a study participant registers.
There's no need to assign a new patient ID; just the act of uninstalling and reinstalling (with the same patient ID) should generate a new encryption key for them.