Bridge provides support to send notifications to individual participants, or to groups of participants interested in specific notification topics. These topics can be either push notifications or SMS notifications. Your client application registers for notifications, and subscribes to the topics the user is interested in.
Additionally, researchers can create topics with Criteria, to send the notification only to those users who meet the criteria.
Configuring Push Notifications
Mobile operating system providers (Apple and Google) provide push notification services (APNS and GCM, respectively). Each service must be configured separately for your study, and then Bridge must be updated with some key information to send push notifications to your app. This configuration is the same regardless of how you use push notifications through Bridge, and only needs to be set up one time.
Bridge engineers will work with your app developers to configure Bridge to send push notifications through the Bridge Study Manager.
Registering for Push Notifications
After a user consents to receive push notifications via the mobile operating system, the system will notify your application and provide a unique device identifier (APNS calls this the device token, and GCM calls this the registrationId).
Your app should send this device identifier to Bridge in order to register for notifications. Bridge returns a registration GUID which you can use to update the device identifier at a later time, as well as to subscribe to notification topics (see below).
It is possible to retrieve a list of device registrations for a participant (if the participant installs your app on multiple devices. there will be more than one).
Some notification services, like APNS, suggest that this device identifier can change over the lifetime of your app's installation. Follow the advice of your push notification provider. Bridge allows the registration to be updated at any time.
Once registered, you will be able to send a push notification to an individual user on the registered device. In the Bridge Study Manager, find an individual user, and navigate to their Push Notifications tab. If they have a registration, they can receive a notification.
To register for SMS Notifications, all you need is a phone number. You'll need to call the Create Notification Registration API, and include the sms protocol and the phone number, with the international calling code. For example:
Only consented participants can register for SMS notifications, and a participant can only register for SMS notifications with a phone number associated to their account.
To send notifications to more than one user, you must create some notification topics. You must define a name and a short name for your topic. The name will be displayed in the Bridge Study Manager (as well as the short name). The short name is displayed in SMS notifications and must be 10 characters or less.
Under Push Notifications in the Bridge Study Manager, developers can create one or more topics. We strongly suggest you create a general topic to apply to all users, but you may create as many additional topics as you need. Apps then subscribe to one or more topics in order to receive topic notifications.
Topic notifications can be sent from the Bridge Study Manager by navigating to the topic under Push Notifications.
NOTE: If a device is unregistered with Bridge, or if a participant withdraws consent, all topic subscriptions are deleted as well.
There are two types of notification topics: manual subscription topics and criteria-managed topics.
Manual Subscription Topics
Manual subscription topics are notification topics that do not have criteria associated with them. Your app must subscribe to any topic for which that user will receive notifications. NOTE: When you call this API, you must specify all topics that the user should be subscribed to. Any manual subscription topics not included in this list will be unsubscribed. NOTE: Criteria-Managed Topics are not affected.
The topic GUIDs can be hard-coded in your application, but it is more advisable to retrieve them from the server or from the user's session, which also contains the list of SubscriptionStatus records.
When the user gives permission to receive remote notifications, register their device and set up some default topic subscriptions (see below). In your app, present the list of topics to the user as a set of preferences to receive different types of notifications, so the user can turn notifications on or off for each topic.
These subscriptions are persisted with the server. In order for a user to receive a notification, they must have subscribed to the topic.
During the first time onboarding experience, you can choose one of several defaults:
- enable all notification types (subscribe the user to all topics to start);
- disable all notification types (do not subscribe the user to any topic, though this may be confusing since they just gave consent to receive notifications); or
- present the user with the topics and allow them to selectively subscribe to some notifications (the most complex onboarding option since it requires some additional UI).
Criteria-Managed Topics are topics that are managed by criteria, such as the participant's language preferences and data group. When the participant first registers for notifications, or when their criteria change, Bridge server automatically subscribes the participant to matching topics. NOTE: Notification topics by app version is not yet supported. NOTE: Manual subscription topics are unaffected and must be subscribed to or unsubscribed from manually.
The content of a notification is defined by the NotificationMessage object. It is currently very simple, but will be augmented over time.
SMS Notification Content
SMS notifications are in the form:
[short name]> [message]
For example, if your topic has name "Monthly Reminder Topic" and short name "Reminder", and you send a notification with subject "Monthly Reminder" and message "This is your monthly reminder", then the SMS notification will appear as
Reminder> This is your monthly reminder
Note that the notification subject is not used for SMS notifications.