Skip to main content

Server SDKs

Statsig server SDKs allow you to run experiments for server-side functionality such as APIs, algorithms, configurations, and infrastructure improvements. The server SDKs evaluate feature gates, dynamic configurations, and experiments locally on your application server.

Here’s how the typical workflow with Statsig's server SDK looks:

Overview of Phases​

  1. Initialization: Setting up the SDK with your server SDK key.
  2. Checking an Experiment: Evaluating experiments and feature gates.
  3. Logging Custom Events: Tracking custom events to analyze your experiment's impact.

Server SDKs

1. Initialization​

  • Call initialize with your server SDK key. This makes a network request to fetch all the rule sets (experiments, feature gates, and configurations) to the application server.
  • Key action: The SDK loads all required configurations to enable local evaluation of experiments, gates, and configs.

2. Checking an Experiment​

  • Use the getExperiment call with a StatsigUser object (which includes a user identifier). This returns the assigned variant for the user. You can retrieve the parameter values from the config object using the get method.

  • For Layer-based experiments, use the getLayer call with a StatsigUser to return the assigned layer and retrieve variant parameters.

  • Use checkGate with a StatsigUser to return a boolean (true or false) based on whether the user passes the configured feature gate rules.

  • Call getConfig to retrieve dynamic configurations for the user. This fetches values from the returned config object.

  • Automatic Exposure Logging: The SDK flushes exposure data to the Statsig servers every 60 seconds by default. For short-lived processes (like serverless environments), call shutdown to force-flush the data when your application exits.

  • Diagnostics: You can verify exposure events in real-time in the Exposure Stream under the Diagnostics tab.

Updating Experiment Configuration​

  • The SDK automatically polls Statsig servers every 10 seconds (configurable) to fetch updated rule sets.
Best Practices

Why is StatsigUser with a userID required for server SDKs?

Check out the UserID Requirements to understand why having a unique userID in the StatsigUser object is critical for server SDK usage.

Setting Default Values for Parameters

It's recommended to include a default value when retrieving parameters from a config object using the get call. This ensures your app gracefully falls back to default behavior if a parameter isn't configured. By default, Statsig returns false for gates that have not yet been set up.

3. Logging Custom Events​

  • Use logEvent to record a custom event for analysis. You can pass the server SDK key, user identifier, and the custom event details.
  • The SDK automatically flushes custom events every 60 seconds.
  • Metrics Lift: Statsig uses logged events to compute experiment metrics. These are updated daily in the Metrics Lift panel of the experiment's Results tab.

Testing Exposure Checks in Development or Staging Environments​

  • You can test exposure checks in non-production environments by setting the environment tier in the initialize call. When testing in development or staging, make sure to toggle Show non-production logs in the Exposure Stream under the Diagnostics tab.

  • To target specific team members for testing, use Manage Overrides in the Statsig console to force specific variants for selected users.

Language-Specific SDKs​

Jump into the technical documentation for your preferred language:

Got questions? Join the Statsig engineering and product team on Statsig Slack.