Overview
Client SDKs run in code that executes on end-user devices, like a website, mobile app, video game, or smart TV app. Server SDKs run on your servers (typically in the cloud), like a web server or API server. Many customers deploy both Server and Client SDKs, letting them gate features on both the client- and server-side for the most control. While this is common, you can get value from Statsig by starting with just one.Usage
Client and Server SDKs follow a similar pattern of setup and usage in-code:- Initialize: Setup the SDK and download the latest values
- Check an experiment/gate: Reference those values to assign an experiment or flag a feature
- Logging custom events: log important app metrics to power your analyses
Conceptual Differences:
- Data Privacy: The Server SDK is presumed to be a secure, multi-user environment, so Server SDKs have access to the full ruleset describing each experiment and gate. Client SDKs fetch only the value for a single user, avoiding exposing the definition of your configurations.
| Server | Client | |
|---|---|---|
| Privacy | Your servers are presumed to be a secure, multi-user environment, so Server SDKs have access to the definition of all configurations in your project | All evaluations are precomputed on Statsig servers and sent down to you client applications. Names are obfuscated, but a savvy user may be able to glean information from the raw response |
| Evaluation Performance | Evaluations are done real-time, without a network request. Very complex configurations can take longer to compute, but in practice, this is rarely an issue. | As all evaluation is precomputed, gate and experiment checks are effectively a dictionary lookup with some computation used for creating and flushing exposure events |
| Initialization Performance | The SDK will make an upfront request for configuration files, then continually poll for any changes to your configurations, updating its internal state when a change is detected | Client SDKs download configurations when you initialize, before which, the SDK may not have usable values. The values aren’t updated mid-session unless you explicitly call updateUser. Additional options are available for performant initialization, see Initializing |
| Users | Server SDKs are designed to run against multiple users, and all SDK methods require a user object for evaluation/logging | Client SDKs are designed to be run with one user at a time. All evaluations are loaded once up front during initialization, and every event logged uses that user object |
| Infrastructure | Server SDKs require you to host your own backend services | Client SDKs run entirely on the client and utilize Statsig’s servers |
Usage Differences:
| Server | Client | |
|---|---|---|
| Initializing | Requires only a secret key, downloads the entire ruleset and syncs it in the background | Requires a client key and a user object. Before/during initialization, the SDK will attempt to fallback to cached values. |
| Checking an Experiment | Requires a user object which is evaluated locally (without a network request) against a ruleset persisted in memory | Does not require a user object, uses a dictionary lookup for values fetched during initialize() |
| User Identifiers | Pass any and all useful user identifiers | Pass any useful identifiers, the SDK also generates a “StableID”, Statsig’s anonymous ID you can use to experiment on a user per-device |
| Logging Events | Requires a user object | Does not require a user object. Note, there is some risk of adblocking log events on client SDKs, which can be minimized by setting up a Custom Proxy |
| Flushing Events | Batched and flushed by the SDK every 60 seconds | Batched and flushed by the SDK every 10 seconds |
| Updating Configurations | Poll Statsig servers for updates every 10 seconds by default (configurable), Streaming possible with some Server SDKs and the Statsig Forward Proxy | Configuration persists until next initialize or updateUser call, recommended to call initialize at the start of each user session |
Difference in initialize/update logic:
Client SDKs:- Configuration persists until next
initializeorupdateUsercall - Recommended to call
initializeat the start of each user session
- Poll Statsig servers for updates every 10 seconds by default (configurable)
- Some SDKs support grpc streaming updates via connecting to the Statsig Forward Proxy
