Skip to main content

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:

  1. Initialization
  2. Checking an Experiment
  3. Logging Custom Events

Server SDKs

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 returned config object to get the value of the parameters required to implement the experiment variant

  • If 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 returned layer object to get the value of the parameters required to implement the experiment variant

  • The 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 otherwise

  • The 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 returned config object to get the value of the parameters required to implement a dynamically configured app experience

  • The 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 calling shutdown in case you're using a script or running in a serverless environment

  • You 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 experience

  • The 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!