Skip to content

[Researchers] FAQs and Beiwe Troubleshooting

Zachary Clement edited this page Dec 6, 2022 · 10 revisions

Why aren't we receiving any data?

We are aware of several factors which can cause users to stop uploading passive data:

  1. The user does not have the correct permissions enabled.
  • iPhone users should have their GPS permission set to "Always", and they should have background app refresh on.
  • Android users should have their GPS permission set to "Always" if available (and "While Using the App" if "Always" is not available on their phone). In addition, they should have any permission on their phone set to "Allow".
  1. The user hasn't opened the app on their phone in over a week.
  2. The user is not connecting frequently to WiFi, or their WiFi network is unstable.
  3. The user is using a power saving mode on their phone.
  4. The user is force-closing the Beiwe app after opening it.
  5. The user does not have any free storage space on their phone, and Beiwe is unable to save any data on the phone.
  6. The user is using a VPN on their phone.
  7. The user accidentally clicked the "Leave Study" button in the app.

Android

If there's no data from an Android phone go through the following steps with the user:

  1. 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.
  2. 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.
  3. 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.

iOS

If there's no data from an iOS phone go through the following steps with the user:

  1. 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.
  2. 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.
  3. The user should connect to a reliable Wi-Fi server for an hour or longer.

Why isn't our subject receiving any survey notifications?

For both iOS and Android phones, a subject must have an internet connection (either WiFi or Cellular) for the notification to be delivered. If a participant is not connected to the internet (for example, because they traveled to a remote area, they turned cellular data off for Beiwe, or they turned their phone on Airplane mode), they will not receive the survey notification until they connect to internet again.

For help with troubleshooting, each participant's page on the Beiwe administrator website shows the times when survey notifications were sent. Please note that these times are relevant to the times when notifications were sent to Google's Firebase server (which then tries to send the notifications to the user) and not when notifications were sent or received by the user's device. A button to manually send notifications is also included on this page so that study staff can send a notification while in a meeting with a study participant.

Android

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 (notice that this is different from the iOS app; Android users will not see available surveys when opening the app from the Home Screen). Turning on Do Not Disturb is another form of disabling notifications.

The Android OS has many ways to silence notifications, deliver them quietly, or deliver them below other notifications. To ensure that participants receive notifications, ensure that their phone is configured to display Beiwe notifications as "loudly" as possible.

iOS

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.

How easy/customizable are Beiwe surveys to configure and use?

Surveys are very easy to set up in the Beiwe backend. Beiwe supports five question types: Informational Text, Slider, Radio Button, Checkbox and 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:

  1. Show survey immediately after registration.
  2. 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.
  3. 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.

Why is our subject getting a "Can't Open File" error during installation?

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 the phone model, here are some of the most common directions:

  1. Apps > My Files > All Files > Downloads
  2. Apps > Samsung > My Files > Download History
  3. My Files > Installation files (APK) > Beiwe

What is the procedure when our study is over?

  1. 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.
  2. 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.
  3. 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.

What is the identifiers file?

The Identifiers file is created when a Beiwe study participant is registered to a study. It contains information for troubleshooting, including: 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 choosing the patientID from the patients window and identifiers from data types (you do not need to specify a date range). Note the phone model recorded for iOS users is hardware based.

I just got a "Forbidden" error when downloading data

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.

Is there an automated way to download data from the backend?

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.

How much data can I download at once from the Beiwe "Data Download" tab?

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 generate 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?

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 (for example, 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) }

How do we analyze the Beiwe raw data?

A list of Beiwe summary statistics is found at Summary Statistics. The available code for summary stats is at 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.

Additional Questions - Onnela Lab Collaborators

If you have additional questions that aren't addressed here, Onnela Lab collaborators can email Onnela Lab Research Coordinator, Hassan Dawood at hdawood@hsph.harvard.edu. 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 the phone, patient ID and study name.

The Onnela Lab does not support the open source software but makes it available for your use. Some open source users have found support by using the Github issues feature for questions in the appropriate Github repository.

OPEN SOURCE Q&A

Please see here Using Beiwe for Open Source Users.

Clone this wiki locally