Allowlisting
This topic describes allowlisting in Optimizely Feature Experimentation.
Allowlisting is one of the easiest ways to QA a flag rule. It lets you run your experiment in either your development or staging environment and shows a specific variation to up to 10 users that you have selected. When the SDK makes an experiment decision for these users, they bypass audience targeting and traffic allocation to see the chosen variation. Users not on the allowlist must pass audience targeting and traffic allocation to see the live experiment and variations.
For example, imagine creating an experiment that compares Variation A and Variation B. You want to QA the experiment's live behavior and show the variations to a select number of key stakeholders. You can create an allowlist that includes the User IDs for the stakeholders who see the live experiment.
To ensure that only your allowlisted users can see the experiment, create an audience targeted to an attribute no user will have or set the experiment's traffic allocation to 0%. After completing QA, establish your production settings for audience targeting and traffic allocation.
Note
Optimizely Feature Experimentation allows you to allowlist up to 10 users per experiment.
Allowlists exist in your datafile in the forcedVariations
field. You do not need to do anything differently in the SDK; if you have set up an allowlist, the Decide SDK
call will force the variation output based on your provided allowlist. Allowlisting overrides audience targeting and traffic allocation. Allowlisting does not work if the experiment is not running, but you can set an experiment to 0% traffic or start in a staging environment to test with allowlisting.
Note
The
forcedVariations
field in the datafile is only related to allowlisted variations. It is not associated with the legacy Full Stack forced bucketing, which uses theGet Forced Variation
orSet Forced Variation
methods. Refer to the legacy documentation Use forced bucketing for more.
Allowlisting Bucketing | Comment |
---|---|
User allowlisting evaluates before these user bucketing methods: |
|
User allowlisting evaluates after this user bucketing methods: | N/A |
Important
If there is a conflict over how a user should be bucketed, then the first user-bucketing method to be evaluated overrides any conflicting method. For more information, view the End-to-end Bucketing Workflow on How bucketing works.
When to use allowlisting
Use allowlisting for previewing, experimenting, and QAing a small group of users:
- As a developer, you can use allowlisting to mock a datafile and test a feature flag or flag variable you are implementing.
- As a QA engineer, you could get added to an allowlist to perform manual tests of feature flags and flag variables in a web UI, or you can add a test runner's 'user ID' to an allowlist to help automate these tests
- You can use allowlisting in a mock datafile. Then copy that datafile and use it as a part of your unit or integration test suite rather than the actual datafile.
When not to use allowlisting
Allowlisting should not be used for large groups of users. We limit you to a maximum of 10 allowlisted users per experiment because:
- Forcing variations with a large number of User IDs will bias your experiment results.
- Allowlisting increases the size of the datafile. The smaller the datafile, the more performant the page will be.
To target an experiment to a larger group of users for QA such as:
- All employees in your organization
- A users on a staging environment
- Any amount of users over 10
use audiences instead. Create an attribute that every user in the group will share, and target the experiment to an audience that contains that attribute.
Create an allowlist
Here's how to create an allowlist of up to 10 users for an A/B Test or Multi-Armed Bandit experiment. You cannot create an allowlist on a Targeted Delivery Rule.
- Navigate to the Flags dashboard and select a Flag Rule you have already created or click Create Flag to create one.

- Select Add Rule and select A/B Test or Multi-Armed Bandit

- Expand the Allowlist: Force up to 10 users into any variation(s) section. Type the User ID and select the variation within the experiment you want to force them into.

Here we are forcing user-1 and user-2 into variation2.
- Click Save.
Important
The User IDs used in the allowlist must match the User IDs passed through the SDK in Activate. Otherwise, allowlisting will not work. These User IDs are often anonymous and cryptic (for example, a cookie value), and you have to copy and paste them.
Updated 4 months ago