Feature Flags, Toggles & A/B Testing

These docs are for using our javascript SDK in a multi-user, server side context. For client side javascript and single-user contexts, try our client js sdk

The node-js-server-sdk and the accompanying docs are open source and hosted on github.

The Basics

Get started in a few quick steps.

1. Create a free account on statsig.com
2. Install the SDK
3. Initialize the SDK
4. Fetch Feature Gates or Dynamic Configs

Step 1 - Create a free account on www.statsig.com

You could skip this for now, but you will need an SDK Key and some Feature Gates or Dynamic Configs to use with the SDK in just a minute.

Step 2 - Install the SDK

Install the sdk using npm or yarn:

npm install statsig-node

yarn add statsig-node

Step 3 - Initialize the SDK

Initialize the SDK using a Server Secret Key from the statsig console:

const statsig = require('statsig-node');

await statsig.initialize(<STATSIG_SECRET>);

initialize will perform a network request. After initialize completes, virtually all SDK operations will be synchronous[^1]–the SDK will fetch updates from Statsig in the background, independently of your API calls.

[^1]: Blog Post: Evaluating Feature Gates in the Statsig SDK

Step 4 - Fetch Feature Gates or Dynamic Configs

Now that your SDK is initialized, let’s fetch a Feature Gate. Feature Gates can be used to create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always CLOSED or OFF (think return false;) by default.

From this point on, all APIs will require you to specify the user associated with the request. For example, check a gate for a certain user like this:

const isGateOn = await statsig.checkGate({ userID: <USER_IDENTIFIER> }, <GATE_NAME>, );
if (isGateOn) {
  // New code branch
} else {
  // Fallback, default behavior
}

Feature Gates can be very useful for simple on/off switches, or more advanced user targeting. But what if you want to return an entirely different configuration to different users? What if you want to be able to send a different set of strings to your client for different locales? Or a different list of products for a new market (or new user)? Enter Dynamic Configs. The API is very similar to Feature Gates, but you get an entire json object you can configure in the console. For example:

Checking a Dynamic Config is nearly identical to checking a gate:

const config = await statsig.getConfig({ userID: <USER_IDENTIFIER> }, <CONFIG_NAME>);

You can then fetch typed Dynamic Config parameters (and provide a default value as a fallback):

const itemName = config.get("name", "Awesome Product!");
const price = config.get("price", 10.0);
const shouldDiscount = config.get("discount", false);

// Or just get the whole object backing this config
const configJson = config.getValue();

We mentioned earlier that after calling initialize most SDK APIs would run synchronously, so why are getConfig and checkGate asynchronous?

The main reason is that older versions of the SDK might not know how to interpret new types of gate conditions. In such cases the SDK will make an asynchronous call to our servers to fetch the result of a check. This can be resolved by upgrading the SDK, and we will warn you if this happens.

For more details, read our blog post about SDK evaluations. If you have any questions, please ask them in our Feedback Repository.

Advanced Setup

If you have a logged in user, or a deterministic way to identify users, pass a userID with each sdk call. You should pass as much information as possible with each check: this will enable you to use more advanced gate and config conditions, like country level or OS/browser level checks.

type StatsigUser = {
  userID?: string | number;
  email?: string;
  ip?: string;
  userAgent?: string;
  country?: string;
  locale?: string;
  clientVersion?: string;
  custom?: Record<string, any>;
};

You can use the SDK to log events associated with the user. These events will be used to power A/B testing metrics in the future, and will show up in the Statsig console under the “Dashboard” tab (coming soon!)

statsig.logEvent({userID: <USER_IDENTIFIER>}, <EVENT_NAME>, <EVENT_VALUE>, <EVENT_METADATA>);

The value and metadata fields are optional.

More Information

For more information, see our SDK documentation on github.