OneBusAway/onebusaway-android

[GSoC] Studies and Surveys Feature

aaronbrethorst opened this issue · 1 comments

aaronbrethorst commented

Overview

We are going to update the app to download a list of objects called Study Participation Requests (SPRs for short), filter out SPRs that the user has already dismissed or responded to, and—if any remain—display one item from the remaining list of SPRs within the app UI.

As the name implies, the SPR is a call-to-action to participate in a study, either on behalf of a transit agency or an academic institution. The SPR contains, among other pieces of information, a title, a body, a list of regions where it will be visible (at least one, but possibly many regions), and the ID of a Qualtrics survey.

An SPR will include the following data:

  • Title - Displayed to users in the app in a call to action
  • Message - Displayed to users in the app in a call to action
  • Post-submission message - Displayed to users after they complete the initial survey
  • Survey ID - the ID of the Qualtrics survey that will be presented by tapping on the call to action
  • Regions - The region or regions in which it will be displayed (e.g. Puget Sound or everywhere)
  • Study ID - A unique identifier that will be used to identify the study and its subsequent calls to action
  • Survey Type:
    • One-time - this is a survey that should only be answered once by a user before it is no longer shown to them. For example, a survey from a transit agency about what improvements a rider wants to see over the next year.
    • Repeated - this is a survey that can be answered by a user many times. For example, feedback on a trip that the user is currently on or has just completed.

Tapping on the call to action will result in the following actions occurring:

  1. The app will generate and store a UUID that will serve as a unique identifier for the user for this and future surveys. (the "Study Respondent ID" or "SRID")
  2. The app will then launch the Qualtrics SDK’s survey UI, showing the survey pointed to by the SPR.
  3. The user will fill out the survey and submit.
  4. Upon submitting the survey, the call to action will be hidden from the user.
  5. An alert will be displayed to the user that shows the SPR’s post-submission message.
  6. The app will check to see if the user has opted into receiving push notifications and prompt them to opt into receiving push notifications if they have not.

The survey will always be provided with the user’s Study Respondent ID, current stop ID, push notification ID (if available), and current location, if known, via Qualtrics’s Embedded Data feature.

The user will also be able to hide the call to action. However, this will not prevent future SPR calls to action from being displayed.

Backend

The backend for this feature will be implemented on the OneBusAway.co server (Obaco for short). This is the same system that powers push notifications for the iOS app today. The backend implementation is out of scope.

You will access the list of SPRs with an HTTP GET request to https://onebusaway.co/api/v1/regions/:region_identifier/study_participation_requests.json

NOTE: this API does not exist yet!

Surveys and Qualtrics

The surveys, themselves, will be powered by the Qualtrics SDK, which will need to be added to the app. Currently, we are not planning on supporting other SDKs, but we also do not want to prevent the adoption of other SDKs in the future.

UI: SPR Call to Action

As described elsewhere, there will need to be a ‘call to action’ UI that displays a title, a ‘Dismiss’ button, and a ‘Participate’ button. Tapping on Dismiss will hide this SPR from the user’s view. Tapping on Participate will present the Qualtrics survey referenced by the SPR.

Details about how and when this is presented still need to be decided, but we'll probably present it as a modal alert.

UI: Settings

Under Settings, the user should be able to find a new area that will allow them to manage their engagement with SPRs and surveys. It should have the following capabilities:

  • A toggle switch that will let them entirely opt out of seeing any new SPRs. By default, it should be "on" (i.e. show me SPRs and surveys).
  • A list of all the SPRs that they have seen and the ability to clear the list of SPRs they have hidden.
  • A list of studies in which the user is currently enrolled. For each study, the user should be able to leave a study, which will be accomplished by sending an HTTP DELETE request to https://onebusaway.co/api/v1/respondents/{SRID}/studies/{STUDY_ID}

UI: Insertion of SPRs and Study Surveys

TBD

Managing Studies

There will be a backend API, https://onebusaway.co/api/v1/respondents/{SRID}/studies.json (NOTE: doesn’t exist yet), that will return a list of available Study objects in JSON format for the participant based upon their Study Respondent ID.

Example

Let’s consider a scenario where a rider fills out a survey to determine if they meet the criteria for participation in a long-term study. This rider would begin by filling out a one-time survey defined by an SPR. Once the study coordinator selected their participants, the coordinator would specify their selected participants’ SRIDs in Obaco and then send a 'Welcome!' push notification to those people who have opted in to push notifications. (Participants who have not signed up for push notifications will still see their surveys in the app.)

Tapping on the 'Welcome!' push notification will show a basic alert that gives the reader some additional information (specified in the notification's body).

As long as the user's device has an SRID, it will always reach out to the https://onebusaway.co/api/v1/respondents/{SRID}/studies.json endpoint to retrieve the latest list of studies in which the user has enrolled. If the user's device does not have an SRID, it will not contact this endpoint.

Surveys loaded through the studies API will be pre-populated with the stop ID and user’s current location, when available.

FAQs

Q: Qualtrics includes features for publishing surveys. Are we going to use those features for publishing surveys to users?

A: No, we will only use Obaco for publishing surveys. In part, this is because it will give us the flexibility to add new survey tools in the future. We will also allow the surveys to be triggered from specific actions from the app, like reaching a destination in a trip.

Q: Can a user be enrolled in multiple studies?

A: Yes. They can be enrolled in any number of studies.

Q: The call to action is what allows a user to enroll in a study, correct?

A: Correct. The study administrator (i.e. a professor or transit agency official) will examine the responses they receive to their call to action and select users to enroll in the study.

Q: Can a single study include multiple surveys?

A: Yes. Depending on its configuration, a single study can include a single survey that the respondent can respond to multiple times, a single survey that the respondent can respond to once, or multiple different surveys that can be responded to 1-n times, depending on configuration.