Onboarding flow

Onboarding flow consists of the entire flow users see after Firefox has successfully been installed or upgraded.

For new users, the first instance of new tab shows relevant messaging on about:welcome. For existing users, an upgrade dialog with release highlights is shown on major release upgrades.

New User Onboarding

A full-page multistep experience that shows up on first run since Fx80 with browser.aboutwelcome.enabled pref as true. Setting browser.aboutwelcome.enabled to false takes user to about:newtab and hides about:welcome.

Default values

Multistage proton onboarding experience is live since Fx89 and its major variations are:

Zero onboarding

No about:welcome experience is shown (users see about:newtab during first run).

Testing instructions: Set browser.aboutwelcome.enabled to false in about:config

Proton (about:welcome)

A full-page multistep experience that shows a large splash screen and several subsequent screens. See Default experience variations for more information.

Return to AMO (RTAMO)

Special custom onboarding experience shown to users when they try to download an addon from addons.mozilla.org but don’t have Firefox installed. This experience allows them to install the addon they were trying to install directly from a button on about:welcome.

For example, a user who visited the addons.mozilla.org page for UBlock Origin while using Google Chrome would see the following:

AMO page for UBlock

And if they install Firefox using that button, instead of the default about:welcome flow, the user would see:

RTAMO welcome page

Note that this uses attribution data added to the browser during the download process.

Testing instructions:

  • Set pref browser.newtabpage.activity-stream.asrouter.devtoolsEnabled as true

  • Open about:asrouter

  • Click Targeting -> Attribution -> Force Attribution

  • Open about:welcome, should display RTAMO page

The default values in the “Force Attribution” devtool point toward uBlock Origin; the demo addon can be changed by replacing the content value with the base64 encoded ID of any addon prefixed with rta: (ex. rta:amlkMS1Nbm54Y3hpc0JQblNYUUBqZXRwYWNr)

General capabilities

  • Run experiments and roll-outs through Nimbus (see FeatureManifests), only windows is supported. FeatureConfig (from prefs or experiments) has higher precedence to defaults. See Default experience variations

  • AboutWelcomeDefaults methods getDefaults and prepareContentForReact have dynamic rules which are applied to both experiments and default UI before content is shown to user.

  • about:welcome only shows up for users who download Firefox Beta or release (currently not enabled on Nightly)

  • Enterprise builds can turn off about:welcome by setting the browser.aboutwelcome.enabled preference to false.

Default experience variations

In order of precedence:

  • Has AMO attribution

    • Return to AMO

  • Experiments (fetched from Nimbus)

  • Defaults

    • Proton default content with screens chosen from the below options based on screen-level targeting:

      • “Welcome Back” device migration screen (shows when isDeviceMigration is true)

      • “Easy Setup” Screen with options to ‘Pin Firefox’, ‘Set default’ or ‘Import from previous browser’, depending on what actions are needed

      • “Language Mismatch” screen which shows when the users system language does not match the download language of Firefox, and offers to download the correct language

      • “Import” screen which shows when the “Import” option was selected on the “Easy Setup” screen, and allows user to import password, bookmarks and browsing history from a previous browser or from file.

      • “Mobile Download” screen which shows a QR code for downloading Firefox for Mobile

      • “Addons Picker” screen which offers a few recommended addons for installation (currently only shows in en-* locales)

      • “Gratitude” screen with a “Start Browsing” CTA.

Upgrade Dialog

Upgrade Dialog was first introduced in Fx89 with MR1 release, and was subsequently used again in the Fx106 MR2022 release. It replaces whatsnew tab with an upgrade modal explaining proton changes, setting Firefox as default and/or pinning, and allowing theme change. Upgrade Dialog has been disabled since Fx117.

Feature Details:

  • Hides whatsnew tab on release channel when Upgrade Modal is shown

  • Modal dialog appears on major version upgrade to 106.

    • It’s a window modal preventing access to tabs and other toolbar UI

  • Supports desired content and actions on each screen, similar to about:welcome. Current defaults show screens for pin, set default, import, mobile, private pin, and data recommendations.

Testing Instructions:

  • Go to about:studies and ensure that the “Upgrade Spotlight Rollout” study is removed.

  • In about:config, set:

    • browser.startup.upgradeDialog.enabled to true.

    • browser.startup.homepage_override.mstone to 105. The dialog only shows after it detects a major upgrade.

    • Ensure pref browser.startup.homepage_override.buildID is empty.

    • Ensure pref browser.startup.upgradeDialog.version is empty. After the dialog shows, browser.startup.upgradeDialog.version remembers what version of the dialog to avoid reshowing.

  • Restart Firefox