Environments

Environments let you run the same experiment on several websites, or on different versions of one website, without duplicating your project. Your pages, audiences and goals are defined once and reused everywhere.

Typical examples:

• A live site and a staging site
• Regional or language sites, for example us, uk and ca
• One site that is served on several subdomains

How it worksCopy Anchor Link

1. Create an environment in your project and give it a rule: a short piece of JavaScript that returns true on the sites where the environment applies.
2. Assign the environment to your experiments.
3. At runtime, the snippet first checks the page conditions. Then, for each experiment, it checks the rules of the experiment's environments and afterwards the audiences. See the snippet sequence.

An experiment without environment is not restricted. With several environments, one matching rule is enough. The full matching table is in the environments guide. An empty rule always matches.

Create and assign environmentsCopy Anchor Link

Creating an environment (fields, API name, default environment, code helper) and assigning it to experiments is described in the environments guide. The API Name is used in the file name of the sub-snippet.

Write the ruleCopy Anchor Link

The rule is the body of a JavaScript function. Return true if the environment applies, otherwise false (or nothing).

// The environment applies on every page
return true;

Inside the rule you can use the tools, available as ablyftTools. ablyftTools.parseUrl() splits the current address into subdomain, domain and tld (and more). For www.example.com the result is www, example and com.

By subdomain. For a site like en.mystore.com:

return ablyftTools.parseUrl().subdomain === 'en';

By domain and top-level domain. For regional shops on different domains:

const { domain, tld } = ablyftTools.parseUrl();
return domain === 'mystore' && tld === 'co.uk';

Live versus staging.

// Live: the production host. Staging: everything else.
return ablyftTools.parseUrl().hostname === 'www.mystore.com';

By an attribute in the page, such as the language of the HTML document:

return document.documentElement.lang === 'de';

Things to keep in mind:

• The rule is checked repeatedly for about 2 seconds, so it can also depend on content that appears shortly after the page loads.
• If the rule throws an error, the error is logged and the environment counts as not matching.
• Keep rules short and without side effects. They run on every page view.

If the same experiment should run on several domains, make sure its pages do not depend on one domain, see Match types.

Sub-snippetsCopy Anchor Link

By default, the main snippet contains all running experiments and every experiment checks its own environment rules. If you enable Create a sub-snippet for an environment, ABlyft additionally creates a snippet that contains only the experiments of that environment.

Use a sub-snippet if you want to load less data on a specific site. You find it under Settings → Snippet → Sub-Snippets. The name contains the API name of the environment:

<script src="https://cdn.ablyft.com/s/12345678-staging.js"></script>

The environment rules are still checked in a sub-snippet. Include either the main snippet or a sub-snippet on a page, not both: a second ABlyft snippet on the same page is ignored.

Edit and deleteCopy Anchor Link

Editing and deleting environments, and the roles required, are described in the environments guide.

TroubleshootingCopy Anchor Link

If an experiment does not run on a site and its page matches, check the environment next, because it is tested before the audiences:

1. Does the experiment have environments assigned? If so, does the rule of at least one return true on this page?
2. Does the rule throw an error? Errors count as "not matching".
3. Do the pages of the experiment use relative URLs?
4. Turn on debug mode and open the browser console. It shows whether an environment is valid. Only if at least one environment is valid, the snippet continues with the audiences. See Debugging.

API accessCopy Anchor Link

Environments of a project can be read through the REST API (projects/{project}/environments, read only). Experiment endpoints accept an environments list with environment IDs. See the REST API.