Server SDKs
Statsig server SDKs enable you to run experiments for any applications improvements driven by server-side functionality including APIs, algorithms, latency, configuration, and infrastructure improvements. Statsig server SDKs evaluate gate, config, and experiment checks locally on your application server.
As shown in the diagram below, implementing an experiment using a Statsig server SDK consists of three phases:
- Initialization
- Checking an Experiment
- Logging Custom Events
1. Initialization
- The server SDK's
initialize
call takes the server SDK key and makes a network request to Statsig servers; this network call fetches all the definition of all configurations in your Statsig project (aka 'rule sets') to your application server to enable local evaluation in the next phase
2. Checking an Experiment
The server SDK's
getExperiment
call takes a StatsigUser object with a user identifier, evaluates the rules for the specified user, and returns the variant that the user is assigned to; use the returnedconfig
object toget
the value of the parameters required to implement the experiment variantIf your experiment is part of a Layer, the
getLayer
call takes a StatsigUser object with a user identifier and returns the variant that the your end-user is assigned to; use the returnedlayer
object toget
the value of the parameters required to implement the experiment variantThe
checkGate
calls takes a StatsigUser object with a user identifier and returns true if the end-user passes the feature gate rules that you've configured on the Statsig console, and false otherwiseThe
getConfig
call takes a StatsigUser object with a user identifier and returns the dynamic configuration based on the rules that you've configured for your end-users; use the returnedconfig
object toget
the value of the parameters required to implement a dynamically configured app experienceThe server SDK automatically flushes all accumulated exposure checks to the Statsig servers every 60 seconds
The server SDK's
shutdown
call resets the state of the SDK and you should call it when the application is about to exit; you can also force-flush accumulated exposure checks by callingshutdown
in case you're using a script or running in a serverless environmentYou can verify that these exposure events are being recorded in Statsig servers using the live Exposure Stream in the Statsig console under the Diagnostics tab of your experiment
The Users and Checks charts in the Diagnostics tab are updated hourly
Updating Experiment Configuration
- The server SDK polls Statsig servers for updates to the rule sets every 10 seconds by default (and can be overridden).
Best Practices
Why is StatsigUser with a userID required for server SDKs?
Learn about UserID Requirements for the StatsigUser while using a server SDK.
Setting Default Parameter Values
Statsig recommends including a default value when you make the get
call to fetch a parameter value from the returned config
object. This will ensure that your application code falls back to the default value for a parameter that's not yet been configured in an experiment, layer, or dynamic config in the Statsig console. For convenience, Statsig by default returns false when you check a gate that has not yet been configured.
Testing exposure checks in development or staging environments
You can test your experiment in development or staging environments by setting the environment tier in the initialize
call. When you do this, you can verify that your exposure checks are working by switching the toggle to Show non-production logs in the Exposure Stream under the Diagnostics tab for your experiment in the Statsig console. By default, the Exposure Stream shows exposure checks logged in production environments.
When you're testing in development or staging environments, you can also target specific members in your team to see a specific variant by adding these members to the override list of a rule or variant group using the Manage Overrides option.
3. Logging Custom Events
The server SDK's
logEvent
call takes the server SDK key with a user identifier along with a custom event that you want to record to analyze the impact of the experiment on your end-user experienceThe server SDK automatically flushes all accumulated custom checks to the Statsig servers every 60 seconds
Statsig uses these custom events to compute metrics as part of your experiment Results; Statsig automatically updates the Metrics Lift panel in the experiment Results tab daily around 9am PST
To start integrating, jump into the technical docs by language:
Got questions? Join the Statsig engineering and product team on the Statsig Slack channel and ask away!