Skip to main content
The first step in using a Statsig SDK is calling initialize(), which retrieves the values you need to evaluate experiments & send events. Before initialization, Statsig SDKs won’t have latest values in-memory, and therefore may return stale values or none at all. Unlike Server SDK initialization, which happens at Server startup, Client SDK initialization happens when a screen is rendered - meaning initialization can have more impact on user experience. Statsig offers several client initialization methods to tune performance to your needs.

General Initialization Flow

initialize will take an SDK key and StatsigUser object. The SDK will then:
  1. Check local storage for cached values. The SDK caches the previous evaluations locally so they are available on the next session if there isn’t a successful network call
  2. Create a STATSIG_STABLE_ID - an ID that stays consistent per-device, which can often be helpful for logged-out experiments.
  3. Set the SDK as initialized so checks won’t throw errors - they will either return cached values or defaults.
  4. Issue a network request to Statsig to get the latest values for all gates/experiments/configs/layers/autotunes for the given user. If the project definition does not change from the most recent cached values, this request may succeed without returning new data.
  5. Resolve the asynchronous initialize call. If the request to the server failed, the SDK will have the cached values or return defaults for this session.
Depending on when you check a gate or experiment after initializing, its possible that you may not have retrieved fresh values yet. Awaiting initialization solves this, with some performance downsides (discussed below).

Client Initialization Strategies

Below are the various strategies summarized at a high level, ordered from most common to least common:
  • Asynchronous Initialization (Awaited): Wait for the initialization network call to finish before rendering content.
  • Bootstrap Initialization: Generate the assignment values on your own server, and pass them down with other request, resulting in zero-latency rendering. Best of both worlds for latency and availability of fresh assignments, but requires additional engineering effort.
  • Asynchronous Initialization (Not Awaited): Do not await the return of the initialization network call. This ensures immediate rendering, but in a state that reflects stale assignments or no assignments available.
  • Synchronous Initialization: Renders immediately, but with stale or no assignments available. First-visit users will never be assigned to gates and experiments.

1. Asynchronous Initialization - Awaited

Ensures latest assignments but requires a loading state
When calling StatsigClient.initializeAsync, the client loads values from the cache and fetches the latest values from the network. This approach waits for the latest values before rendering, which means it is not immediate but ensures the values are up-to-date.