Client vs Server SDKs
Statsig offers client and server SDKs to enable experimentation and feature management across different parts of your application. This document outlines when you should choose each.
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
After initialization, both Client and Server SDKs evaluate experiments/gates without a network request, and typically in less than 1ms. Checks in the Statsig SDKs are designed to be very efficient.
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
Server SDKs:
- Poll Statsig servers for updates every 10 seconds by default (configurable)
- Some SDKs support grpc streaming updates via connecting to the Statsig Forward Proxy
Available SDKs
Client SDKs
Server SDKs
For more detailed information on each SDK, please refer to their respective documentation pages.
Got questions? Join the Statsig engineering and product team on the Statsig Slack channel and ask away!