Using Environments for Conditional Evaluation outside of Production
All of our SDKs allow you to set the environment tier your app is currently in during initialization.
If you'd like to evaluate feature gates, dynamic configs, and/or experiments to different values in lower environments vs. Production, you simply need to set the correct environment in your code when initializing and configure the corresponding Feature Gate rules in the Statsig Console to evaluate differently for a given environment tier. The sections below detail how to do this.
SDK Usage
There are two main levers for setting environment-
- Environment-specific SDK keys- used to control which rules are downloaded to a given SDK
- Environment tier at SDK initialization- used for evaluating rules
Environment-specific SDK Keys
Configuring an environment-specific SDK key enables you to control which rule-sets are sent to a given SDK based on environment. For example, if an SDK it initialized with an API key set to development, it will not know about any rules that have been set for any other environment. For more information, see the Per-Environment API keys section further down this page.
Environment Tier Parameter
It's important to note that SDK keys can correspond to multiple environments, so you need to set the environment tier on SDK initialization explicitly, even if you are using an environment-specific SDK key. You can set the environment via the StatsigOptions parameter. All SDKs accept an SDK key and an (optional) StatsigOptions dictionary of parameters.
One of these options is the environment parameter, which has a tier field. The tier can be any of your pre-configured environments (see below for how to configure new environments). If the environment tier is unset, all checks and event logs are considered "production" data.
Please note, that per-environment API keys do not affect the evaluation context of feature gates, dynamic configs or experiments: they only restrict which rules the SDK can download.
For this example, lets say we are setting the parameter for our development environment/app.
Client SDKs take an SDK Key, User, and StatsigOptions parameter:
await statsig.initialize(<SDK_KEY>, user, {environment: {tier: 'development'}})
Server SDKs take just an SDK Key and StatsigOptions parameter:
await statsig.initialize(<SDK_KEY>, {environment: {tier: 'development'}})
These examples in js and node illustrate the general pattern - refer to your language's specific SDK documentation for more information.
Using Environments in Feature Gates
Head on over to the Console and create a new Feature Gate. For this example, I'll call mine "development mode." It will only pass for our development apps.
At rule creation, you will have the opportunity to configure the target environments for that rule. Check the Specify Environments checkbox and choose which environments you want your rule to be enabled for. By default unless otherwise specified, a rule is enabled for ALL environments.
Press "Save" and that's it! You can now see which environment(s) your rule is enabled for inline, directly below the rule name.
You can also easily filter rule-sets by environment via environment filters in the upper right-hand corner of your rule-set within your Feature Gate.
A rule's target environment(s) can be edited at any time. To do so, tap the "..." on the rule. Then select "Edit Rule" and specify any environment changes you want to make.
Configuring Environments
By default, your Statsig Project will have three environments configured- Development, Staging, and Production. If you would like to add more environments or rename these default environments you can do so via Project Settings. The only environment you cannot modify or delete is Production, which must exist within every Project.
To add or edit environments, go to Project Settings -> Environments & Keys
Tap Edit to configure your environments, as well as reorder the hierarchy of environments via drag-and-drop. Note- the order of environments has no impact on any configured rule logic within your Feature Gate, but is rather meant as a tool to convey to your teams the rollout order/ relative hierarchy between environments.
Per-Environment API keys
For privacy and security reasons, you can also configure per-environment API keys via this tab. This means that any SDK initialized with the API keys generated here, will only see the rules for which it has access. For example, if an SDK it initialized with an API key set to development, it will not know about any rules that have been set for any other environment.
To generate a new, environment-specific key tap Generate New Key and specify the target environments. Please note that the three default environments that are built into all new Projects on Statsig share the same server and client-side API keys.
