Logo

Feature Flags, Toggles & A/B Testing

Everything you need for turbocharging your modern product development

Javascript Client SDK for Statsig

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

The js-client-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

You can install the statsig SDK via npm, yarn or jsdelivr.

npm install statsig-js

yarn add statsig-js

via jsdelivr:

Statsig is available from jsdelivr, an open source CDN. We use this installation method for using Statsig on www.statsig.com! Go ahead, inspect the page source.

To access the current primary JavaScript bundle, use:

https://cdn.jsdelivr.net/npm/statsig-js/dist/statsig-prod-web-sdk.min.js

To access specific files/versions:

http://cdn.jsdelivr.net/npm/statsig-js@{version}/{file}

Step 3 - Initialize the SDK

After installation, you will need to initialize the SDK using a Client SDK key from the “API Keys” tab on the Statsig console.

These Client SDK Keys are intended to be embedded in client side applications. If need be, you can invalidate or create new SDK Keys for other applications/SDK integrations.

Do NOT embed your Server Secret Key in client side applications

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

await statsig.initialize(<STATSIG_CLIENT_SDK_KEY>, { userID: <USER_IDENTIFIER> });

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.

if (statsig.checkGate(<YOUR_GATE_NAME_HERE>)) {
  // Gate is on
} else {
  // Gate is off - fallback 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 on the server. For example:

const config = statsig.getConfig(<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);

Advanced Setup

You should provide a user object whenever possible to your initialize() call, passing as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks). If the user is not known at SDK init time, you can still fetch values for logged out users until the user is known. At that point, update the gates and configs for the user using:

await statsig.updateUser({ userID: <USER_IDENTIFIER>});

The User Object can be populated with a number of schematized attributes, or your own custom fields:

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(<EVENT_NAME>, <EVENT_VALUE>, <EVENT_METADATA>);

More Information

For more information, see our SDK documentation on github.

FAQ

What kind of browser support can I expect from the SDK?

We strive to keep the SDK as lightweight as possible, while supporting as many browsers as possible. The primary feature that our SDK relies on which may not be supported by all browsers is a javascript Promise. You may wish to polyfill a Promise library to ensure maximum browser compatibility. We recommend taylorhakes/promise-polyfill for its small size and compatibility.

Featured Resources