Initialization Strategies
Overview
We now offer several strategies for initializing StatsigClient — allowing customers to fine-tune and minimize latency. The various strategies carry some tradeoffs, and should be carefully considered based on your performance requirements and experimentation needs.
Below are the various strategies summarized at a high level, ordered from most common to least common:
- Asynchronous Initialization (Awaited): Ensures user assignments are available after initialization but adds latency due to awaiting fresh assignments being fetched over the network from Statsig servers.
- Bootstrap Initialization: It's best of both worlds in terms of latency and availability of fresh assignments. Use Sync bootstrapping if your architecture permits and you have the engineering bandwidth to implement the server-sdk to generate the client init payload.
- Asynchronous Initialization (Not Awaited): This ensures immediate rendering, but in a state that reflects stale assignments or no assignments available (resulting in default values being used).
- After initialization, the client will then fetch fresh assignments over the network from Statsig. Subsequent calls to check assignments may result in different assignments than the initial state and therefore render a different treatment (this is referred to as "flicker"). This mimics the old behavior of
StatsigProvider.waitForInitialization=false.
- After initialization, the client will then fetch fresh assignments over the network from Statsig. Subsequent calls to check assignments may result in different assignments than the initial state and therefore render a different treatment (this is referred to as "flicker"). This mimics the old behavior of
- Synchronous Initialization: Ensures immediate rendering but with stale or no assignments available. First-visit users will never be assigned to gates and experiments. These users will only see updated assignments after they do a hard-refresh of the website. Effectly, all assignment information is 1 pageload stale.
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.
Example:
2. Bootstrap Initialization
Ensures both latest assignments with no rendering latency
Bootstrapping allows you to initialize the client with a JSON string. This approach ensures that values are immediately available without the client making any network requests. Note that you will be responsible for keeping these values up to date.
Example:
3. Asynchronous Initialization - Not Awaited
If you want to fetch the latest values without awaiting the asynchronous call, you can call initializeAsync and catch the promise.
This approach provides immediate rendering with cached values initially, which will update to the latest values mid-session.
Be aware that the values may switch when checked a second time after the latest values have been loaded.
Example:
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. The client fetches new values in the background and updates the cache. This approach provides immediate rendering, but the values might be stale or absent during the first session.
Example:
These strategies help you balance the need for the latest gate / experiment assignment information with the need for immediate application rendering based on your specific requirements.