-
Notifications
You must be signed in to change notification settings - Fork 51
Survey Notification Resends, The App Heartbeat, and KeepAlive Notifications
The Beiwe Platform, in particular the Beiwe2 iOS App, uses push notifications for Surveys. This The server-side notifications are technically optional, but to aquire high quality data they are effectively necessary.
- The Beiwe Platform uses push notifications to inform your participants that they need to take a survey.
- Participants on iOS require that we resend notifications, for reasons I get into below.
- You have the option to manually re-send a survey notification on a per-participant basis, but you should use it sparingly.
- These details and the timing of those resends are configurable in your Study's Device Settings.
The fastest way to get participants to uninstall the Beiwe App and drop out of your study is to bombard them with too many notifications.
For reasons dull and numerous, Apple iOS does not provide a perfect way to keep an app open in the background. We have had to do a lot of work and testing to keep the app open and collecting the type and quantity of sensor information that we do. Once the app gets stopped by iOS the only fix is for the participant to take an action that opens the app. By Apple's design, the only way to do this is to send a push notification.
(Android provides a feature that means it isn't as dependant, but it is slowly becoming more iOS-like.)
The Apple and Android notification services are usually rock solid, but there is a special token the device must periodically send to the server. There are no known bugs in the prompt delivery of this token, and its status is noted on the Participant Page of every participant. If this token is missing it nearly always means the app is not running or has been uninstalled. If it is missing then notifications will fail, and there is a component of the platform that will check on and retry until the notification service confirms everything works. You can usually completely ignore this, I list it here so that you are not confused by it later.
There's two systems here, Survey Notifications, and what we call the App Heartbeat and KeepAlive Notifications. Its not actually that complex, and we have APIs to view the underlying data it collects.
It's dead simple - the app pings the server every 5 minutes.
- (Aug 2026: iOS has a bug where it is hitting more frequently.)
The KeepAlive Timer - this is a duration and message that you can configure in your Study's Device Settings.
- If the app hasn't checked in recently, it sends that message.
- The default is 1 hour.
- The default message is "Beiwe may not be running correctly, please open the Beiwe app."
This "heartbeat" history is available through our APIs, which you can find in our reference api script. It may be useful as a rough proxy for when the app was running, but it does not and cannot cover periods where the device was without coverage.
The problem we are fighting in iOS is the fact that notifications can be deleted or cleared by the participant before the app receives it. This happens when an iOS user swipes horizontally on the lock screen or in the Notification Center to remove a notification or taps on the notification clear button. (The UI before iOS 26 used to actually say "delete" and "clear", this is no longer the case, but these are both same action for our purposes.)
As long as the participant opens the app while there is a notification pending, the app is updated to make the appropriate surveys visible.
Be aware that some people are ~nearly pathologically~ unaware that they are manually deleting their notifications. (This blindness is similar to the phenomenon where a computer user will dismiss a warning dialog without reading it or registering that they have done so.)
The Beiwe Apps update the server with information about received notifications every time they contact the server. This means it is at least as frequent as the App Heartbeat, every 5 minutes, provided network connectivity is present.
The Backend tracks sent time, received time, and checkin time for every notification and resend. This information is all visible on the Notification History page on a per-participant basis, and is available through our APIs.
When a Survey Notification goes unacknowledged by the device for a long enough, we identify it, resend it, and start that timer again.
The resend timer is a duration that you can configure in your Study's Device Settings.