Configuration Options

(Note: UI to configure these options are not yet available. In the short term, please contact Bridge dev team to configure these values.)

(Dev notes: These values are configured in the DynamoDB table prod-heroku-NotificationConfig.)

These values can be configured per study.

studyId (String) The study ID you are configuring for study burst notifications. Example: "sage-mpower-2"

appUrl (String) URL that links back to the app (or to the study website, if for some reason the app is not installed). Example: http://mpower.sagebridge.org/

burstDurationDays (Number) The length of each study burst in days. This is the number of days the study burst is active, not the full cycle between each burst. Example: 14

burstStartEventIdSet (String Set) Set of activity event IDs that mark the start of each study burst. Example: ["enrollment", "custom:activityBurst2Start", "custom:activityBurst3Start", "custom:activityBurst4Start", "custom:activityBurst5Start", "custom:activityBurst6Start", "custom:activityBurst7Start", "custom:activityBurst8Start", "custom:activityBurst9Start"] Note that you need to pre-end activity event IDs (other than "enrollment") with "custom:". For example, the activity event ID is "activityBurst2Start", but the schedule references it as "custom:activityBurst2Start".

burstTaskId (String) The task ID that represents completing today's activity burst. Example: "study-burst-task"

earlyLateCutoffDays (Number) Number of days to determine when the cutoff is for "early burst" vs "late burst" messages. Example: 5

engagementSurveyGuid (String) Defunct

excludedDataGroupSet (String Set) Data group that contains users that should not receive notifications, whether it's because they're unsubscribed or because they're in a different segment of the engagement study or otherwise. Example: ["notification_unsubscribed"]

missedCumulativeActivitiesMessagesList (String List) Messages to send for users who miss cumulative activity days within a single study burst. Worker will pick one at random. Example: ["We need you! Contribute to the mPower study today.", "We need you! Completing the 2 week burst helps us understand Parkinson’s disease."]

missedEarlyActivitiesMessagesList (String List) Messages to send to users who miss consecutive activity days early in the study burst. Worker will pick one at random. Example: ["Don't forget your mPower burst has started! Use the daily activities to focus on your health.", "The mPower burst in underway. We have noticed you have missed a few days, your contribution is important."]

missedLaterActivitiesMessagesList (String List) Messages to send to users who miss consecutive days late in the study burst. Worker will pick one at random. Example: ["You are doing great! Don’t forget to complete your daily check-in.", "Keep up the good work! Don’t forget to do your daily mPower activities."]

notificationBlackoutDaysFromStart (Number) Number of days at the start of the study burst where we should not consider sending notifications. Example: 3

notificationBlackoutDaysFromEnd (Number) Number of days at the end of the study burst where we should not consider sending notifications. Example: 3

numActivitiesToCompleteBurst (Number) Number of activity days that the user needs to complete to complete the study burst. After this, we do not message the user for this burst. Example: 10

numMissedConsecutiveDaysToNotify (Number) Number of consecutive days the user misses before we send them a notification. This includes the day we send the notification. Example: 3

numMissedDaysToNotify (Number) Number of cumulative days within a single study burst that the user misses before we send them a notification. This includes the day we send the notification. Example: 4

preburstMessagesByDataGroup (Map of String to String List) Messages we send to each user the day before the study burst begins, keyed by data group. Each entry is a list of possible messages, and the worker picks one of those messages at random. This doesn't count against the notification limit. Example: {"gr_BR_AD", ["Time to complete the burst. If you log, it could possibly provide you with new insights about your health. Please do it right now or get into the habit of taking it after you taking your medications.", "Time to complete the burst. What you are doing right now is directly helping future parkinson's patients. Please do it right now or get into the habit of taking it after you taking your medications."], "gr_BR_II":["Time to complete the  burst. If you log, it could possibly provide you with new insights about your health. Remember that you thought the best time to this was", "Time to complete the burst.  What you are doing right now is directly helping future parkinson's patients. Remember that you thought the best time to this was"]}

Example

In mPower 2.0, we currently set the following configuration values (to match the study burst schedule defined in Bridge server):

• burstDurationDays = 14
• burstStartEventIdSet = enrollment, custom:activityBurst2Start, custom:activityBurst3Start, ... , custom:activityBurst9Start
• burstTaskId = "study-burst-task"

Suppose we numMissedConsecutiveDaysToNotify=2 and numMissedDaysToNotify=3. Consider the following scenarios:

• User A does no activity on day 1 nor on day 2. On day 2 (at around noon PDT, which is when the Notification Worker runs), the system detects that user A has done no activities for 2 consecutive days and sends a notification.
• User B does activities on day 2 and day 4, but skips day 1, day 3, and day 5. On day 5, at around noon, the system, detects that user B has missed 3 cumulative days in this study burst and sends a notification.
• As a special case, let's suppose we also set notificationBlackoutDaysFromStart=5. In User B's scenario, on day 5, since we're still in the blackout period, the system doesn't send a notification (or even check User B's activies). On day 6, the user does their activities. The Notification Worker runs, notices that the user missed 3 cumulative days, but the user also did today's activities. In this case, the Notification Worker is smart enough to know not to send a notification, since the user did their activities today.

The Notification Worker will also not send a notification in the following cases:

• The account has no phone number associated or the phone number is not verified.
• The participant has not signed consent.
• The participant has already received a notification during this study burst.

Template Variables

SMS message strings can include template variables that look like ${url} or ${studyCommitment}. These are automatically substituted by the Notification Worker, based on configuration. (Or in a few specific cases, hardcoded.) Valid template variables include:

url - URL link to the app, configured by appUrl in config.

studyCommitment - Text that the participant provided in the engagement study. This is stored in the Engagement report for date 2000-12-31 (an arbitrary constant meaning "global"). This report is a flat map where keys are the survey question IDs and values are the answers. (NOTE: For now, we use "benefits". Confirm w/ Larsson the correct names once the survey is set up.) Since the survey guid is generated randomly for each env and each study, we get it from engagementSurveyGuid in config.