Launching Incident Response Pref Flips

As of Firefox 129 (and 128.2 ESR), Firefox supports flipping any pref via Nimbus. This is done with the prefFlips feature. The JSON Schema definition for the feature value can be found here.

Warning

This feature is not intended for use in experimentation. If you want to do an experiment on some number of prefs in Firefox, you must register these prefs with the Feature Manifest. This ensures that prefs controlled via Nimbus are subject to code review. See the docs on Desktop pref experiments for more information.

Because the incident response feature can change any pref, it should be used with caution. Remember: with great power comes great responsibility.

Only the release management team can approve incident reponse pref flips.

Behaviour

When a client enrolls into an experiment/rollout using this feature, Nimbus will set (or unset) all the prefs to the values specified. Prefs on the user branch will persist through startup and be available immediately. Prefs set on the default branch will not persist through startup and will not have their correct values until Nimbus finishes initialization.

When the client unenrolls, all prefs will be restored to their values before enrollment. If the pref did not exist before enrollment, it will be cleared if it was set on the user branch. The default branch does not support clearing, so the pref and its value from the enrollment will persist until the browser closes.

If the client is enrolled in both an experiment and a rollout then only the experiment will take effect. This behaviour is likely to change once multiple enrollment support is added to desktop.

Multi-feature

The incident response feature cannot be used with other features.

Launching a Pref Flip

Create a new experiment in Experimenter with an appropriate public name (this will appear in about:studies) for Firefox Desktop.
Fill in the "overview" page as appropriate.
Fill in the "branches" page:
1. Select the prefFlips feature.
2. Check the "This is a rollout (single branch)" checkbox.
  This is not strictly required, but rollout enrollment can be dialed up or down without requiring ending the experiment and re-launching. If you do not want to use a rollout so that you can set different prefs on different branches you likely want to run an experiment, in which case this feature is not appropriate for your use case.
3. Enter a description for the "Control" branch.
4. Enter a value for the prefFlips (see the example configuration).
Fill in the "Audience" page:
channel
You must specify a channel to use this feature. If you want to change a pref across multiple channels you must repeat this process for each channel.
Min Version
You must specify a minimum version. The minimum versions supported are 129 on the Nightly, Beta, Aurora (developer edition), and Release channel and 128.2 on the ESR channel.
Advanced Targeting
If you want to enroll the entire population, choose "No Targeting - All users". Otherwise, select an appropriate targeting criteria.
If a targeting criteria does not exist, one will have to be added. See the advanced targeting FAQ or ask for help in #ask-experimenter on Slack.
Sticky Enrollment
Experiment targeting is re-evaluated every time the client checks for new recipes. If you want the selected advanced targeting to only be evaluated during enrollment, check this box.
Note: Rollouts can re-enroll after unenrolling (e.g., if enrollment percentage decreased and then increased). In these cases, rollouts will re-evaluate targeting, ignoring the sticky flag.
Percent of Clients
Enter the percent of clients you wish to enroll. This value can be changed after launch for rollouts.
On the Summary Page, request launch.
Experiments and rollouts using the incident response feature cannot be launched to preview. We highly reccomend you QA these recipes on the staging instance of experimenter first.
Note: Experimenter may report errors with your recipe configuration. You must fix them before requesting launch. Ask in #ask-experimenter on Slack.
Ask release management to approve and launch the rollout.
Note: If you are a member of release management, you must get another member to to approve and launch. Experimenter requires a 2 person sign-off to launch experiments: the person who requests the launch cannot be the person who approves it.

Example Configuration

{
    "prefs": {
        "the.pref.to.set": {
            "branch": "user",
            "value": "hello world"
        },
        "another.pref.to.set": {
            "branch": "default",
            "value": true
        },
        "unset.this.pref": {
            "branch": "user",
            "value": null
        }
    }
}

Causes of Unenrollment

Mismatched Types

If you attempt to set a pref to a value of the wrong type, the pref will fail to set. This will cause the enrollment to end. This will result in a unenrollment event (glean, legacy) being submitted with the following data:

Glean Field	Legacy Field	Description
`reason`	`reason`	The string `"prefFlips-failed"`
`pref_name`	`prefName`	The pref that that failed to set.
`pref_type`	`prefType`	The type of the existing pref.

Conflicts with setPref Experiments

If a user is enrolled in a incident response pref flip and then enrolls in a setPref experiment that changes the same prefs, they will be unenrolled from the incident response rollout. This will result in a unenrollment event (glean, legacy) being submitted with the following data:

Glean Field	Legacy Field	Description
`reason`	`reason`	The string `"prefFlips-conflict"`
`conflicting_slug`	`conflictingSlug`	The slug of the experiment that caused the unenrollment.

User Pref Changes

If a pref that is controlled by an incident response rollout is changed, either by the user or client code, the client will be unenrolled. This will result in an unenrollment event (glean, legacy) being submitted with the following data:

Glean Field	Legacy Field	Description
`reason`	`reason`	The string `"changed-pref"`
`changed_pref`	`changedPref`	The pref that triggered the unenrollment.

Warning

Behaviour

Multi-feature​