Microsurvey Overview
This page provides context on the microsurvey feature and the architecture surrounding the implementation. The microsurvey feature is an extension of the messaging framework, and allows us to display surveys to our users in a less intrusive way. It also allows us to capture user’s sentiment on any specific app’s features such as the homepage.
Note that this page was created during the MVP phase of the microsurvey project.
The microsurvey feature is composed of two main UI components. One is the prompt and one is the actual survey.
The prompt is an invitation to start the survey and it is shown when the triggers are met. The triggers are determined through the mobile messaging infrastructure and should be specified by the Nimbus recipe. For testing, we have created a trigger in which the user will be eligible to receive the survey after visiting the homepage twice.
The prompt is shown until the user completes the survey, closes the survey or reached the maximum number of display specified in the mobile messaging configurations.
- This title of the prompt which can be customized, but also has a fallback string.
- The close button dismisses the survey and it won't be shown again.
- The continue button starts the survey and shows the survey sheet. It can be customized, but also has a fallback string.
The survey sheet is shown after the user clicks on the button in the prompt. It is a modal that starts at medium detent (50%) on iPhone and large detent (100%) on iPad. The user will be able to view and fill out the survey.
- The sheet grabber allows users to expand or dismiss the sheet. If the user dismisses the sheet by dragging down, this will close the sheet and show the prompt.
- The close button dismisses both the sheet and the prompt.
- The question and options both can be customized. There are fallback options for the options, but the question is required for the microsurvey message to appear.
- The submit button will send the survey result via telemetry and is enabled if at least one option is selected.
- The privacy notice navigates the user to open a new tab. The prompt will still be shown unless the user has completed the survey and views the confirmation page.
| User Selected Option | Confirmation Page |
|---|---|
 |
 |
MicrosurveySurfaceManager is the name of the class that uses the mobile messaging infrastructure to handle the configuration of the microsurvey. This class will contain the rules on when to show the microsurvey and provide the content based on the experiment recipe on the Nimbus side. The MicrosurveySurfaceManager will contain an instance of the GleanPlumbMessageManager and an instance of the GleanPlumbMessage which are part of the messaging framework.
Specifically for the microsurvey, when the prompt appears, this triggers an impression and the message has been interacted with when the user taps on the continue button for the survey.
If you are not familiar with the existing messaging framework, please take a look here first. The microsurveys are built on top of the already existing messaging framework, with a couple extra fields to configure the survey.
On the prompt, you can customize the prompt title by using the same title field as a normal message. This can be configured with the Nimbus recipe or set with a pre-landed string id that is in our app bundle, which is already localizable. The button title can also be configured using the same button-label field.
For example:
{
"messages": {
"homepage-microsurvey-message": {
...
"title":"Help us make Firefox better. It only takes a minute.",
"button-label":"Continue",
...
},
}
For the survey, you can control the question, survey options and UTM parameter for the privacy policy link. For the survey question, use the text field at the same level as the title one, similar to the latter where you can provide either a string or pre landed string id.
{
"messages": {
"homepage-microsurvey-message": {
...
"title":"Help us make Firefox better. It only takes a minute.",
"button-label":"Continue",
"text":"How satisfied are you with your Firefox homepage?",
...
},
}
To customize the survey options, icon and UTM parameters, we have to add the microsurveyConfig field object. For the survey options, there exists a new field called options, it’s an array in which each item will represent a possible survey option for the user to select. Currently, the array is composed of type Text, which you can read more about our bundle types here.
For the icon, add the icon field under microsurveyConfig. This is related to the asset used next to the survey question. It should change for each survey feature, but it needs to be a valid icon resource id indicated in our app. The list of standard images can be found here.
For the UTM parameters, add the utm-content field. This is related to the utm-content value that we pass in as a query param for our privacy notice. It should change for each survey feature, but it can be any string. Here is an example case:
https://www.mozilla.org/en-US/privacy/firefox/?utm_medium=firefox-mobile&utm_source=modal&utm_campaign=microsurvey&utm_content=homepage
{
"messages": {
"homepage-microsurvey-message": {
...
"title":"Help us make Firefox better. It only takes a minute.",
"button-label":"Continue",
"text":"How satisfied are you with your Firefox homepage?",
...
"microsurveyConfig":{
"utm-content":"homepage",
"icon":"homeLarge",
"options":[
"Very satisfied",
"Satisfied",
"Neutral",
"Dissatisfied"
"Very dissatisfied"
]
}
},
}
Before targeting any specific feature, triggers must be added pre landed on the app or included as part of the JSON recipe.
At the moment, there is one trigger landed specifically to target features:
-
SECOND_HOMEPAGE_VIEW: Indicate an user has entered twice to the home screen.
For adding more triggers please consult with the engineering team.
{
"messages": {
"ios-homepage-csat-microsurvey-en": {
"trigger-if-all": [
"USER_EN_SPEAKER",
"MORE_THAN_24H_SINCE_INSTALLED_OR_UPDATED",
"SECOND_HOMEPAGE_VIEW"
],
"style": "MICROSURVEY",
"surface": "microsurvey",
"text": "How satisfied are you with your Firefox homepage?",
"button-label": "Microsurvey/Microsurvey.Prompt.Button.v127",
"title": "Microsurvey/Microsurvey.Prompt.TitleLabel.v127",
"microsurveyConfig": {
"utm-content": "homepage",
"icon": "homeLarge",
"options": [
"Microsurvey/Microsurvey.Survey.Options.LikertScaleOption5.v127",
"Microsurvey/Microsurvey.Survey.Options.LikertScaleOption4.v127",
"Microsurvey/Microsurvey.Survey.Options.LikertScaleOption3.v127",
"Microsurvey/Microsurvey.Survey.Options.LikertScaleOption2.v127",
"Microsurvey/Microsurvey.Survey.Options.LikertScaleOption1.v127",
"Microsurvey/Microsurvey.Survey.Options.LikertScaleOption6.v129"
]
}
}
}
}
The two main UI files in the codebase are MicrosurveyPromptView and MicrosurveyViewController.
The MicrosurveyViewController also has sub-components that make up the survey’s view:
- MicrosurveyTableView
- MicrosurveyTableHeaderView - survey question
- MicrosurveyTableViewCell - survey options
- MicrosurveyConfirmationView - confirmation page that shows cute firefox image
Since we have two separate UI components, we have two separate State objects: MicrosurveyPromptState and MicrosurveyState. The prompt acts as a subview to the BrowserViewController and the survey itself acts as its own screen since it's a modal view.
Following the Redux pattern, the MicrosurveyPromptAction and MicrosurveyPromptState will be created to handle the actions and state associated with the prompt. Since the data for the microsurvey lives in a separate dependency, the MicrosurveyPromptMiddleware will also be created and holds an instance of the MicrosurveySurfaceManager, which we discuss in more details in the sections below. The model from the MicrosurveySurfaceManager is returned in the form of the MicrosurveyModel in which the MicrosurveyPromptMiddleware uses to dispatch the initialize action.
MicrosurveyPromptActionType There are currently three types of actions that can be associated with the prompt. The Action should contain the following: User Actions:
- showPrompt
- closePrompt
- continueToSurvey
Middleware Actions:
- initialize
- dismissPrompt
- openSurvey
MicrosurveyPromptState The State should contain the following:
- showPrompt - determine whether the prompt should be shown
- showSurvey - determine whether to show the survey
- model - provides the data for the prompt
MicrosurveyPromptMiddleware
The Middleware is mainly responsible for generating the model that populates the microsurvey and creates an instance of the MicrosurveySurfaceManager that also determines whether the prompt should be shown or not as well as sending telemetry.
Similarly to the prompt, we also create a MicrosurveyAction and a MicrosurveyState that will handle the actions and state associated with the survey. The model for the survey should get passed in from the prompt state. The MicrosurveyMiddleware for the survey will be created to send telemetry after the user submits their response to the survey, which is done through the MicrosurveySurfaceManager.
MicrosurveyActionType There are currently three types of actions that can be associated with the survey. The Action should contain the following: User Actions:
- closeSurvey
- submitSurvey - does not dispatch a new action; sends telemetry via mobile messaging infrastructure
- tapPrivacyNotice
- surveyDidAppear - mainly to call telemetry that view has been shown
- confirmationViewed
Middleware Actions:
- dismissSurvey
- navigateToPrivacyNotice
MicrosurveyState The State should contain the following:
- shouldDismiss - determine whether to close the survey
- showPrivacy - determine whether to navigate to privacy notice
MicrosurveyMiddleware
The Middleware is mainly responsible for sending telemetry through MicrosurveyTelemetry.