Client SDKs

Introduction to Statsig client SDKs for web, mobile, and TV platforms, covering common concepts, initialization, evaluation, and event logging.

Statsig client SDKs enable you to run experiments for user experience improvements in applications running on end-user devices. These applications include web and mobile apps, television and gaming apps, and other consumer electronics apps.

Implementing an experiment using a Statsig client SDK consists of three phases:

Initialization
Checking an Experiment
Logging Custom Events

1. Initialization

The client SDK's initialize call takes the client SDK key and a StatsigUser object. The SDK checks local storage for cached values from a previous initialization, then makes a network request to Statsig servers. This network call fetches precomputed configuration parameters for the specified user and stores them in local storage on the client device. If the request fails, the SDK uses previously cached values.
Statsig's server latency for initialize calls is generally 10ms (p50). Latency for a given client varies by distance from Statsig's servers. The client SDK has a built-in timeout of 3 seconds, configurable through StatsigOptions when you initialize the SDK.
The StatsigUser object you provide in the initialize call should include the userID field used to identify the end-user. The client SDK also generates a device identifier called stableID to enable experiments for users who are not signed in and have no userID. You can override this stableID through StatsigOptions using the overrideStableID parameter when you initialize the SDK.

2. Checking an Experiment

After the initialize call completes, any subsequent getExperiment call synchronously returns the variant assigned to your end-user (parameters are defined when you set up an experiment on the Statsig console). Use the returned config object to get the value of the parameters required to implement the experiment variant.
If your experiment is part of a Layer, the getLayer call returns the variant assigned to your end-user. Use the returned layer object to get the value of the parameters required to implement the experiment variant.
The checkGate call returns true if the end-user passes the feature gate rules configured on the Statsig console, and false otherwise.
The getConfig call returns the dynamic configuration based on the rules configured to target your end-users. Use the returned config object to get the value of the parameters required to serve a dynamically configured app experience.
All of the above (checkGate, getExperiment, getLayer, and getConfig) log an exposure at the time the check is made, before returning a value to the caller.
The client SDK automatically flushes all accumulated exposure checks and events to the Statsig servers every 10 seconds.
You can also force this flush by calling shutdown, which resets the state of the SDK. Call shutdown when the application is about to exit.
Verify that exposure events are recorded in Statsig servers by checking the live Exposure Stream in the Statsig console under the Diagnostics tab of your experiment.
The Users and Checks charts in the Diagnostics tab are updated hourly; the Metrics Lift panel in experiment Results is updated daily around 9am PST.

Updating Experiment Configuration

The experiment configuration received in response to the initialize call persists until you make another initialize call (recommended when the end-user starts a new session) or an updateUser call (recommended when an end-user attribute changes). Both calls trigger a re-evaluation of all experiment configuration for the end-user.

Using StatsigUser

Learn how to use StatsigUser while using a client SDK.

Setting Default Parameter Values

Statsig recommends including a default value when you make the get call to fetch a parameter value from the returned config object. This ensures that your application code falls back to the default value for a parameter that hasn't yet been configured in an experiment, layer, or dynamic config in the Statsig console. For convenience, Statsig returns false by default when you check a gate that hasn't yet been configured.

You can test your experiment in development or staging environments by setting the environment tier in the initialize call. When you do this, you can verify that your exposure checks are working by switching the toggle to Show non-production logs in the Exposure Stream under the Diagnostics tab for your experiment in the Statsig console. By default, the Exposure Stream shows exposure checks logged in production environments.

When you're testing in development or staging environments, you can target specific members in your team to see a specific variant by adding these members to the override list of a rule or variant group using the Manage Overrides option.

Cached values fallback

If the initialize request fails, the SDK falls back to values cached for the user. The cache key is important: because session-related values can change on every initialize call, using the full user object as the cache key prevents cache matches.

The SDK defines the cached "user" by the set of all IDs (the userID and all customIDs). If another field in the user object changes, the SDK still loads the cached values as long as the IDs are the same.

If you have fields that uniquely identify a user and are not in userID or customIDs, you can override the cache key. Go to the documentation for your specific SDK. This option is available in JavaScript-based SDKs (js, react, react native, expo) and Android/iOS native SDKs.

3. Logging Custom Events

The client SDK's logEvent call takes a custom event to record for analyzing the impact of the experiment on your end-user experience.
The client SDK automatically flushes all accumulated logged custom events to the Statsig servers every 10 seconds.
Statsig uses these custom events to compute metrics as part of your experiment Results. Statsig automatically updates the Metrics Lift panel in the experiment Results tab daily around 9am PST.

Custom event logging can sometimes be blocked by third-party plugins. To work around this, set up a custom proxy using your domain for log event API calls. For more information, go to Custom Proxy for Statsig API.

To start integrating, go to the technical docs by language:

Got questions? Join the Statsig engineering and product team on the Statsig Slack channel and ask away!

Was this helpful?