# Environments

URL: https://docs.ablyft.com/guides/audiences-and-delivery/environments/

> Restrict an experiment to certain websites or stages, such as live and staging, or one site per country.



An **environment** is a label with a rule that says on which website, or on which version of a website, an experiment is
allowed to run. Typical uses:

* A live site and a staging site, so a test only runs where you want it
* One site per country or language, for example `us`, `uk` and `ca`
* One website that is served on several subdomains

You define environments once in your project and then assign them to your experiments. Pages, audiences and goals stay
shared.

> This page is the short, task-oriented overview. The rules are small pieces of JavaScript. How to write them, with
> examples, sub-snippets and troubleshooting, is explained in
> [Environments (developer guide)](https://docs.ablyft.com/developers/installation/environments/).

## Do you need environments?

If your project is a single website, you can ignore environments. An experiment **without** an environment can run
everywhere the snippet is installed.

Use environments if you run the snippet on more than one site, or if you want to keep a test away from a staging site
(or the other way around).

## Create an environment

1. Open your project and go to **Settings → Environments**.
2. Click **Create** and fill in the form:
   * **Color:** a label color that helps you to recognize the environment.
   * **Name:** a clear, descriptive name such as `Staging`. Unique in the project.
   * **API Name:** only for advanced users. Letters, numbers, dashes and underscores, filled in from the name and unique
     in the project. It is used in the file name of the [sub-snippet](https://docs.ablyft.com/developers/installation/environments/#sub-snippets).
   * **Rules:** JavaScript that returns `true` on the websites where the environment applies. The **Code Helper** next
     to it offers ready-made expressions (`subdomain`, `domain`, `tld`) that you can copy.
   * Optional: **Description**, **Use as project default** (new experiments get this environment automatically; only one
     environment per project can be the default, and there is none until you enable it) and **Create a sub-snippet**.
3. Save.

A developer can help you with the rule. How to write rules, with examples, is explained in the
[developer guide](https://docs.ablyft.com/developers/installation/environments/#write-the-rule).

## Assign environments to an experiment

1. Open the experiment.
2. In the card **Environments** ("Restrict to environments") in the right column, click **Edit**.
3. Select one or more environments and click **Save**.

Environments are not part of the form for creating an experiment, you set them on the experiment's page. The card then shows the assigned environments. Without any, it shows **No restrictions set**.

| Situation               | Result                                                   |
| ----------------------- | -------------------------------------------------------- |
| No environment assigned | The experiment can run everywhere.                       |
| One environment         | The experiment runs only where its rule applies.         |
| Several environments    | The experiment runs where **at least one** rule applies. |

Good to know:

* Environments are checked after the page matched and **before** [audiences](https://docs.ablyft.com/guides/audiences-and-delivery/audiences/).
* If you set an environment as **Use as project default**, new experiments get it automatically.
* Cloning an experiment copies its environments.
* Changing the environments of a live experiment is published automatically.

If an experiment should run on several domains, set up its pages so that they do not depend on one domain, see
[Match types](https://docs.ablyft.com/guides/audiences-and-delivery/pages/#match-types).

## Find the environments of your experiments

In the experiment list, the column **Environments** shows the assigned environments with their color.

## Edit or delete an environment

You can edit an environment at any time, and ABlyft publishes the change if experiments use it. An environment that is
used by experiments cannot be deleted. Open the environment and check **Used in experiments**, remove it from these
experiments, then delete it. Creating, editing and deleting requires the role member, admin or owner.

## Next steps

- [Environments (developer guide)](https://docs.ablyft.com/developers/installation/environments/): Write rules, sub-snippets and troubleshooting.
- [Pages & URL targeting](https://docs.ablyft.com/guides/audiences-and-delivery/pages/): Define where an experiment runs.