Skip to main content

Introduction

The onboarding feature enables experimentating with the 'new user onboarding flow'. The onboarding flow is presented to the user on each new install, and is made up of a series of full screen 'views', referred to as 'cards'. The purpose of the onboarding flow is to enable the user to configure a small number of app enhancing settings. Each card provides context for each setting and the ability to take an appropratie action, or skip to the next card.

The onboarding feature enables customize each card's:

  • title copy
  • body copy
  • imagery
  • button copy
  • button actions
  • number of buttons (one or two)
  • sequencing

About this document

This document is a guide for staff who wish to configure the new user onboarding flow through the experimenter interface.

It is also a living document:

  • the onboarding feature may be under active development
  • card types may be added
  • card attributes may be added

Scene setting

The onboarding feature is built on top of Nimbus, Mozilla's experimentation platform. Nimbus allows you to send bits of configuration to application features from Experimenter, the web-application staff use to launch and manage experiments and rollouts.

Using Experimenter in the general case is documented elsewhere, so this document is specifically concerned with configuring the onboarding feature.

References

For the most up-to-date configurations, the main code base will always be the best place to check.

danger

The onboarding feature is a first run experiment

Creating an experiment

Only values that differ from the card's default values need to be provided to Experimenter. E.g:

Existing default card​

{
   "cards":{
      "welcome": {
         "title": "Onboarding/Onboarding.Welcome.Title.v114",
         "body": "Onboarding/Onboarding.Welcome.Description.v114",
         "order": 10,
         "image": "welcome-globe",
         "link": {
            "title": "Onboarding/Onboarding.Welcome.Link.Action.v114",
            "url": "https://www.mozilla.org/privacy/firefox/",
         },
          "buttons": {
            "primary": {
              "title": "Onboarding/Onboarding.Welcome.Action.v114",
              "action": "next-card",
            },
          },
          "type": "fresh-install",
          "prerequisites": ["ALWAYS"]
      }
   }
}

Experimenter card config​

{
   "cards":{
      "welcome": {
         "title": "A new title",
      }
   }
}

Output (the merged result of the existing card and experiment card)​

   "cards":{
      "welcome": {
         "title": "A new title",
         "body": "Onboarding/Onboarding.Welcome.Description.v114",
         "order": 10,
         "image": "welcome-globe",
         "link": {
            "title": "Onboarding/Onboarding.Welcome.Link.Action.v114",
            "url": "https://www.mozilla.org/privacy/firefox/",
         },
          "buttons": {
            "primary": {
              "title": "Onboarding/Onboarding.Welcome.Action.v114",
              "action": "next-card",
            },
          },
          "type": "fresh-install",
          "prerequisites": ["ALWAYS"]
      }
   }

Feature Definition

The onboarding feature is split into several values:

  • conditions
  • cards
  • dismissable

Conditions​

The conditions table is a set of triggers, like messaging, that can be used on cards to include or exclude them from appearing. The conditions list is a json of valid JEXL expressions. These expressions can be used in the prerequisites or the disqualifiers fields in cards. E.g.:

"conditions": {
    "ALWAYS": "true",
    "NOT_INSTALLED_TODAY": "days_since_install > 0"
}

Card definition​

AttributeTypeDescriptionDefault Value
titleFree text or TextIDThe title text displayed to the user""
bodyFree text or TextIDThe body text displayed to the user""
orderIntUsed for sequencing cards10
imageImageIDThe image to show for a particular cardwelcome-globe
linkNimbusOnboardingLinkAn optional link. If available, it will appear on the card. If not, no link will be present.null
buttonsNimbusOnboardingButtonsThe configuartion for buttons.A Skip button with a default action of going to the next card.
prerequisitesList of JEXL keysThe list of JEXL keys guiding whether a card can show up for certain users. All prerequisites must be true for a card to show.[]
disqualifiersList of JEXL keysThe list of JEXL keys guiding a card should not show up for certain users. If any disqualifiers are met, then the card will not show.[]
typeTypeIDThe type of onboarding the user is seeing.fresh-install

Default cards​

By default, the app is bundled with a collection of pre-defined cards which will be used if no other configuration is provided for the cards. See the appendix for an overview of the default cards or the code the most up-to-date configuration.

FieldTypeDescriptionDefault
titleFree text or StringIDThe title of the link"Learn more about our privacy policy"
urlStringThe url to which the link would take the user."https://www.mozilla.org/privacy/firefox/"

NimbusOnboardingButtons​

FieldTypeDescriptionDefault
primaryNimbusOnboardingButtonThe primary button on the card, coloured blue.A Skip button.
secondaryNimbusOnboardingButtonAn optional second button. If defined, it will be in grey, below the primary button.null

NimbusOnboardingButton​

FieldTypeDescriptionDefault
titleFree text or StringIDThe title of the button"Skip"
actionOnboardingActionsThe action the button will take.next-card
OnboardingActions​
ActionDescription
next-cardWill take the user to the next card
sync-sign-inWill take the user to the sync sign in flow
request-notificationsWill request to allow notifications from the user
set-default-browserWill send the user to settings to set Firefox as their default browser
open-default-browser-popupWill open up a popup with instructions for setting Firefox as their default browser
read-privacy-policyWill open a webview where the user can read the privacy policy

Dismissable​

This is a property for the whole onboarding, and controls whether there is an x at the top of the screen or not. This is a simple boolean value:

{
    "dismissable": true
}

Available resources

TextID​

All existing app strings are available to Experimenter. See the full list here. Note, that only strings with a tableName and a key can be used. Free text may also be used instead of a string resource.

⚠️ Localization of Free Text is not currently supported.

Image resources​

Base Resources​

Resource IDDescription
welcome-globeAn image of a person hugging the firefox logo
sync-devicesAn image of a variety of devices
notificationsAn image of notifications

Campaign - Challenge the Default​

Resource IDDescription
welcome-ctdThe welcome image for CTD campaign.
sync-devices-ctdThe sync image for CTD campaign.
notification-ctdThe notifications image for CTD campaign.

Appendix

Default cards overview​

Default Welcome Card​

AttributeValue
typefresh-install
titleOnboarding/Onboarding.Welcome.Title.v114
bodyOnboarding/Onboarding.Welcome.Description.v114
link
- titleOnboarding/Onboarding.Welcome.Link.Action.v114
- url"https://www.mozilla.org/privacy/firefox/"
imagewelcome-globe
ordering10
buttons
- primary
-- titleOnboarding/Onboarding.Welcome.Action.v114
-- actionnext-card
prerequisitesALWAYS

Default Sync card​

AttributeValue
typefresh-install
titleOnboarding/Onboarding.Sync.Title.v114
bodyOnboarding/Onboarding.Sync.Description.v114
imagesync-devices
ordering20
buttons
- primary
-- titleOnboarding/Onboarding.Sync.SignIn.Action.v114
-- actionsync-sign-in
- secondary
-- titleOnboarding/Onboarding.Sync.Skip.Action.v114
-- actionnext-card
prerequisitesALWAYS

Default Notification card​

AttributeValue
typefresh-install
titleOnboarding/Onboarding.Notification.Title.v114
bodyOnboarding/Onboarding.Notification.Description.v114
imagenotifications
ordering30
buttons
- primary
-- titleOnboarding/Onboarding.Notification.TurnOnNotifications.Action.v114
-- actionrequest-notifications
- secondary
-- titleOnboarding/Onboarding.Notification.Skip.Action.v115
-- actionnext-card
prerequisitesALWAYS