Optimizely will be sunsetting Full Stack Experimentation on July 29, 2024. See the recommended Feature Experimentation migration timeline and documentation.

Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket
These docs are for v2.0. Click to read the latest docs for v3.0.

Create and manage environments

Optimizely environments allow you to organize your projects into logical sections that correspond to your development environments. You use environments to verify an experiment's features, feature tests, and A/B tests before deploying changes to your application. Using environments let you run a single experiment in some contexts and pause in others. You can turn an experiment on and run it for your team so they can test it, but leave it turned off for visitors.

Every Optimizely project starts with one environment (and one datafile) named Production. When you set up an environment, Optimizely generates:

  • Environment-specific datafile– The datafiles generated by these additional environments represent the current states of all experiments within your Optimizely project. Each environment-specific datafile represents only the state of the experiments within that environment.
  • Unique SDK key– The key determines the URL of the environment's datafile, which ensures that the URL won’t be easily guessed. For SDKs that provide native datafile managers (currently iOS, tvOS, and Android), you can use the SDK key to initialize the SDK with with the corresponding environment's datafile. See Initialize a mobile SDK .

When you create an environment, you will also be asked to provide an environment key. This key is used for programmatic access to the environment: for example, if you were to modify your environments using Optimizely's REST API.

You can rename the default environment and add more environments as needed. Many mature optimization teams have access to separate staging and production environments. Separate environments reduce the risk of accidentally launching an unfinished or unverified test to the live site. We recommend that you add a staging environment to your project to use for QA testing before running experiments in your Production environment.



Environments are currently available only for Optimizely X Full Stack projects.

Environments and security

Improve security by restricting permissions for starting and stopping experiments in an environment to collaborators with Publisher permissions. This limits the number of people who can change your experiments’ statuses or move them from one environment to another.

We recommend keeping access open to everyone in local or development environments and restricting access in production environments. By default, the production environment is limited to Publishers and above, which is the same permission level that applies if you are not using the environments feature.

Create environments

To create an environment:

  1. Navigate to Settings > Datafile.
  2. Click New Environment.
  3. Enter the environment name and key. Specify the permission level you want to set for experiments in the environment.
  4. Click Create Environment.

The Environment Key and Datafile URL for the new environment display on the Settings page.

  1. Implement the datafile in your application.
    Learn more about accessing the datafile and best practices for datafile management.



Experiments are paused by default in any new environments you create, even if they were already running in the default environment.

Change experiment status in an environment

When you use multiple environments for a project, the Environments column on the Experiments dashboard displays icons that represent the state of the experiment in each environment

To change an experiment’s status in an environment:

  1. Click the Actions icon (...) for the experiment.
  2. Select Run or Pause for the environment where you want to change the experiment’s status.

Learn how to designate which environment is shown to visitors in our topic about datafile versioning and management.

Rename an environment

To rename an environment:

  1. Navigate to Settings > Datafile.
  2. Click the Actions icon (...) for the environment you want to rename.
  3. Click Settings.
  4. Enter the new name for the environment and click Save Environment.

Archive an environment

You can archive environments if they aren’t being used anymore (except the primary environment, which can't be archived). Archiving deactivates all the datafiles in an environment, replacing them with an empty file, and removes the environment as an option for experiments.

If experiments are running in the environment when you archive it, they will stop because archiving empties the datafile.

To archive an environment:

  1. Navigate to Settings > Datafile.
  2. Click the Actions icon (...) for the environment you want to archive.
  3. Click Archive.

Results by environment

As you build, launch, and promote your experiments from lower level environments into production, you will want to differentiate between results that were triggered during your QA process and results that were triggered by live users. To do so, we recommend that you create an attribute for environments, then set the attribute's value with the environment from which an event is sent. This will allow you to use segmentation to filter your results by this attribute.