...

How to Model Activity Burst

App will need to use the Publish Custom Event API to publish custom events for "activityBurst1Start", "activityBurst2Start", etc... (Note that we can schedule off custom events, but if there are duplicate event IDs, we schedule off the first such event. So each activity burst start will need to use a different event key.) "activityBurst1Start" should be the same as enrollment date (or possibly whenever the user upgraded to mPower 2), and the subsequent burst start times should be every 3 months after that (or whatever interval we decided).

If the user reinstalls, the app can use the Get Activity Events API to verify if the user already has activity burst events configured. Note that we use this API because it already exists, and because we assume the app wants to know where the user is in an existing study burst (if any). If it turns out that the app doesn't need to know where the user is in the study burst, we could always implement a "publish activity event if not exists" API, but that API doesn't exist yet.

...

Requirements

mPower 2.0 is a new study, so we don't have to deal with users upgrading from mPower 1.0, so we can use enrollment to trigger study bursts.

A user will have a study burst every 13 weeks, which roughly divides the year into 4 quarters, and starts and ends the study burst on the same day of week every burst. A study burst will last 2 weeks. There will be 9 study bursts, lasting 2 years + 1 extra study burst at the end of the two years.

Implementation

When a user is enrolled in the study, Bridge Server will automatically generate custom events activityBurst1Start, activityBurst2Start, ... , activityBurst9Start. (We can't have duplicate event IDs, so each event ID needs to be different.)

In Bridge Server, we'll have a schedule set up, scheduled off of each of activityBurstNStart, which schedules daily events for the next 2 weeks. (Note that for custom events, we add the prefix "custom:" to the event key. Example: "custom:activityBurst1Start".)

When the user first installs the app, the app will ask Bridge for events for the next 2.5 years. This will generate all the events on Bridge Server. This means we can assume the events will always exist for each user. (IMPORTANT: Bridge Server currently limits the Get Activities call to a max of 15 days. In order to get activities for the next 2.5, the app will need to make Get Activities calls 15 days at a time.)

When the app completes each activity, it will need to call the Update Activity API to mark that activity as completed.

Registering for Notifications

In order for the app to receive SMS notifications, the app will need to call the Create Notification Registration API.

Open Question: How does the notification get routed to the app? Does AWS take care of this?New Feature: Automatic custom events per study.

New Feature: Bridge can schedule off of each of a list of events, rather than one of a list of events.

Alternatives

Alternative #1: Create 9 different schedules, one for each study burst. This means less work on Bridge Server, but it requires us to manually create 9 identical schedules. This is not recommended, as maintaining 9 identical schedules leads to replication errors.

Alternative #2: Instead of creating a bunch of custom events, we should implement compound schedules, eg daily activities every 2 weeks, repeat the schedule every 13 weeks for 9 iterations. This is not recommended as it increases the complexity of the Bridge Scheduler tremendously. It would be much simpler to simply create two very simple features (automatic custom events, and schedule for each event) and combine them than to make one very complex feature.

Sending Notifications

We want to be able to send SMS notifications on an individual basis. Topics and subscriptions doesn't really fit the use case, so we'll need to create a worker facing "send SMS to user" API. Note that this message should be marked as "Promotional" rather than "Transactional", since it's not really transactional in nature.

SMS vs In-App Notifications

...

We need to give users a way to opt-out of receiving SMS notifications. We only send SMS notifications if a user hasn't engaged with their study burst in 2+ days, so at that point, opting out of SMS notifications should also opt the user out of the study. So the users will need to respond to the SMS with "QUIT STUDY" to opt out.Open Question: How to handle opt-outs? Can this be configured in AWS?AWS handles this automatically for us (see https://docs.aws.amazon.com/sns/latest/dg/sms_manage.html#sms_manage_optout). Part of the notification should inform the user that they can choose to quit the study replying with QUIT.

As a supplement, we can have an SMS Notification setting in the app, which can mark the user with a data group (or profile attribute). The Notification Worker can then filter on these data groups (or profile attributes).

Important: SMS opt-out is account wide. If a user opts out of SMS from Bridge, this means they also no longer receive SMS to verify their phone or get a phone sign-in link for any study. Note that email opt-outs are only 0.2% of our emails. We expect SMS opt-out rates to be lower. Therefore, this is unlikely to affect more than a small handful of users. We can look into SMS legal requirements and granular opt-outs as a Stretch Goal, but we've decided that it's not an mPower 2.0 launch blocker, nor is it necessary to design this out upfront. Also note that, unlike email, we don't get any notifications if a user opts out of SMS. We have to manually poll SNS to determine users who have opted out. As a Stretch Goal, we can build a system to poll users who have opted out of SNS and do any necessary follow-up.

NOTE: It was determined that a user opting out of SMS notifications isn't required to leave the study.

In order to prevent spurious SMS sign-in messages, we want to make Reauth more robust. See

Activity Burst Notification Worker

We will need to add worker APIs for:

• get notification registrations for userget activity events for user
• get activity history for user
• send notification to user
• (optional) get schedule plan

(NOTE: These APIs all exist for study researchers, but they do not yet exist for workers.)

The worker will be scheduled to run daily at (for example) 20:00 UTC (12pm PST / 1pm PDT). The worker will iterate over every user in the given study, and for each user:

1. Check that the user has registered for 's data groups and/or profile attributes to see if they are eligible for SMS notifications. If they haven't, don't bother doing any work. Just not, skip.
2. Look up the user's activity events to determine where they are in the study burst.
3. If the user is in an activity burst, get all their activities since the start of the activity burst to see if they've been completing their activities. (Note that the only way to look up We can either check all of a user's activity is by their guid, so the worker will need to know the activity guids for the activity burst.)activities, or we can check the user's activities for a specific schedule.
4. If certain conditions happen (the user has done less than X activityes activities in at least Y days), send a notification to the user using the Send Notification API.

...