Skip to content

[Developers] Survey scheduling enhancements and push notifications spec

Jump to bottom Edit New page
zagorsky edited this page Jan 16, 2018 · 1 revision

Note: this spec has not been implemented. It was for a project that didn't come through.

Architecture plan

We're changing the architecture so that survey scheduling logic will run on the server (not on the phone), and the server will send a push notification to the app when it's time for the app to display a survey notification.

  • This change is to be effective for both regular surveys and audio (voice recording) surveys.

  • At registration, the app will upload a unique push notification token (along with the username and registration password that it already uploads).

  • The server will run scheduling logic and determine when it's time to send a survey to each participant. When it's time for a participant to take a survey, the server will use that participant's unique push notification token to send the participant's app a push notification.

  • When the app receives the push notification, it will display a notification icon that looks the same as the old local notification icons.

  • The old architecture has the app store the survey questions JSON spec on the phone, and on some frequency check for updates to the question set. The new architecture will have the app ask for a new survey question JSON spec for each survey. The app should request the survey question JSON spec from the server as soon as possible after receiving the push notification. There are two reasons for having a new survey question JSON spec for each survey:

    • This gives us confidence that the most up-to-date survey was actually delivered to the participant
    • This enables future architectural changes like sending different surveys based on the answers to previous surveys

  • These push notifications and the subsequent request for the survey questions JSON spec will work over mobile data as well as over WiFi. A push notifications is a negligibly small packet of data, and a JSON survey file is about 1 kilobyte; this should consume at most a small fraction of a megabyte of data per month.

  • Each study will be marked as either old (existing architecture: survey scheduling logic runs on the phone) or new (survey scheduling logic runs on the server, which sends push notifications). At registration (in the server's response to the /register_user or /register_user/ios/ call), the server will tell the app whether the app is registered on a new study or an old study. If the app is registered on a new study, it'll use the architecture described; if it's on an old study, it'll use the old survey scheduling architecture.

  • The only change to the survey questions JSON spec will be the removal of the timings attribute. The current survey questions JSON spec looks like this:

{
   'content': [],
   'settings': {},
   'survey_type': 'tracking_survey'|'audio_survey',
   'timings': []
}

The new survey questions JSON spec will look like this:

{
   'content': [],
   'settings': {},
   'survey_type': 'tracking_survey'|'audio_survey'
}

What schedules we'll support

  • Weekly recurring surveys (what we currently support): schedule a survey for a certain time on a certain weekday, and the survey gets asked at that time every week. You can add as many of these as you like to a single survey, for example: ["Mondays at 1:23pm", "Mondays at 6:15pm", "Tuesdays at 1:23pm",...]
  • Relative and absolute dates: all dates can be either absolute dates (e.g. "May 1, 2017") or dates relative to the date that the participant registered their phone in that study (e.g. "25 days after registration").
  • Specific-time surveys: schedule a survey for a certain time (precision of one minute) and a certain date. You'll be able to add as many of these as you like to a single survey, for example: ["May 1, 2017, 5:16pm", "May 3, 2017, 5:16pm", "May 5, 2017, 5:16pm",...] or ["Day 21, 5:16pm", "Day 23, 5:16pm",...]
  • Date ranges on weekly recurring surveys: only allow a weekly recurring survey to be asked during a particular date range. For example, a Monday/Wednesday/Friday schedule ["Mondays at 9:45am", "Wednesdays at 9:45am", "Fridays at 9:45am"] that only runs between May 5, 2017 and May 15, 2017 (inclusive), or between day 15 and day 25 after enrollment. Outside of that range, the survey doesn't get asked. For example, since May 5, 2017 is a Friday, this survey won't appear on Wednesday, May 3, but it will appear on Friday, May 5.
  • The ability to combine all of the above. For example, one survey could send at 7:35pm on Thursdays between days 45 and 90 of the study, and also at 9:15pm on May 26th, 2017.

Ensuring compatibility with older app versions

All studies that are on the server before the push notification architecture change is rolled out will be considered "old style" (current architecture: survey scheduling logic happens on the phone). All studies created after the push notification architecture change is rolled out will be considered "new style" (survey scheduling logic is on the server, with push notifications sent to the app).

Nothing will change for old studies: their surveys will continue to operate as usual, researchers will be able to add/edit/delete surveys on the old studies, and those surveys will continue to use the old survey JSON spec. Participants also need to be able to use new versions of the Beiwe iOS and Android apps in an old study. So the new versions of the iOS and Android apps must support both old and new surveys, and at registration, figure out which type of study they're in and determine which style of survey to use.

To enroll in a new study, a participant must have a new version of the Android or iOS app; at registration, the app must upload a push notification token along with the username and registration password.

At registration, the server will send the app a variable that says whether the study is new style or old style. Here's a summary of how compatibility will work:

Old study on server New study on server
Old app version Works: nothing needs changing Won't work (app can't upload push notification token, so server won't allow it to register)
New app version (app uploads push notification token at registration) Works: at registration, app sees that study is old-style, and app reverts to old-style (downloading survey JSON files and running survey scheduling logic on the phone) Works

When all old-architecture real studies (not counting the test studies) have finished, we can remove this compatibility code from the apps and just assume that participants will no longer register their phones in an old study.

Handling time zones

The Aurora study is taking place in different time zones within the US. We'll assume that the participant's time zone stays the same for the duration of the study; even if someone moves or travels, they'll still get notifications based on the time zone their phone was in when they registered the app.

At registration (when the Android app calls the /register_user API endpoint, or the iOS app calls /register_user/ios), along with all the other data in that request (username, password, etc.), the app will submit the name of the time zone it's in, with the key timezone. The time zone name will be based on the tz database format. The time zones we care about supporting are:

America/New_York America/Chicago America/Denver America/Phoenix America/Los_Angeles America/Anchorage Pacific/Honolulu

If the app can't detect its own time zone, it can upload "null" or "none" or whatever; if the server can't parse it as a valid time zone, it'll default that participant to America/New_York.

What the app will have to do

  • Generate a push notification token and submit it at registration

  • At registration, detect whether it's on an old or new study, and which version of the survey scheduling architecture to enable as a result

  • If it's registered in a new study, receive push notifications from the server, and when it receives a notification:

    • Display a survey icon in the notifications bar
    • Request the survey questions JSON spec from the server
    • Store the survey questions JSON spec until the participant takes and submits that survey

  • If it's registered in an old study, use the old architecture, i.e., run all the scheduling logic on the phone, use timers and local notifications, and periodically ask the server for updated survey JSON.

Also see: Additional AURORA Group Requirements

Add a custom footer
Add a custom sidebar
Clone this wiki locally