Initializing SDKs

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 previous evaluations locally so they are available in the next session if there is no successful network call.
2. Create a STATSIG_STABLE_ID: an ID that stays consistent per device, which is useful for logged-out experiments.
3. Set the SDK as initialized so checks don't throw errors. Checks 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 hasn't changed 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 uses cached values or returns defaults for this session.

Depending on when you check a gate or experiment after initializing, fresh values may not be available yet. Awaiting initialization resolves this, with some performance tradeoffs (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. It isn't immediate, but ensures the values are up to date.

const { client, isLoading } = useClientAsyncInit(
  YOUR_CLIENT_KEY,
  { userID: "u_123" }
);

if (isLoading) {
  return <div>Loading...</div>;
}

// Continue with initialized client

2. Bootstrap Initialization

Ensures both latest assignments with no rendering latency

Bootstrapping allows you to initialize the client with a JSON string. Values are immediately available without the client making any network requests. You are responsible for keeping these values up to date.

Your server serves the configuration payload to your client app on page load (for web implementations) or during app launch (for mobile implementations).

// Server-generated initialization values
const initValues = getStatsigValuesFromServer(user);

const client = useClientBootstrapInit(
  YOUR_CLIENT_KEY,
  { userID: "u_123" },
  initValues
);

// Client renders immediately with server values — no network request

3. Asynchronous Initialization - Not Awaited

To fetch the latest values without awaiting the asynchronous call, call initializeAsync and catch the promise. This approach provides immediate rendering with cached values initially, then updates to the latest values mid-session.

4. Synchronous Initialization

Ensures immediate rendering but uses cached assignments (when available)

When calling StatsigClient.initializeSync, the client uses cached values if they are available. New values are fetched in the background and the cache is updated. This approach provides immediate rendering, but values may be stale or absent during the first session.