On this page

Elixir Server SDK

Statsig's Next-gen Elixir Server SDK built in our [Server Core](/server-core) framework

Elixir Core on Github, Hex Package

Setup the SDK

  1. Install the SDK

    To use the SDK, add the following to your mix.exs:

    elixir
    {:statsig_elixir, "~> 0.8.0"},
    The SDK is written using rustler_precompiled, which downloads a precompiled binary by default. You can also build the Rust code within your project by cloning statsig-server-core
    bash
    cd statsig-server-core/statsig-elixir/ 
# set the environment variable 
FORCE_STATSIG_NATIVE_BUILD="true" mix compile

  2. Initialize the SDK

    After installation, initialize the SDK using a Server Secret Key from the Statsig console.

    Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.

    An optional options parameter accepts a StatsigOptions object to customize the SDK.

    Statsig.ex uses GenServer to manage the Statsig instance (which is written in Rust). Add Statsig to your Supervision Tree:

    elixir
    # Initializing, with StatsigOptions
sdk_key = "secret-key******" # your secret key
statsig_options = %StatsigOptions{enable_id_lists: true}

# Add to your supervision tree 
statsig_spec = %{id: Statsig, start: {Statsig, :start_link, [sdk_key, statsig_options]}}
children = [
    # Other Apps
    statsig_spec
]
res = Supervisor.start_link(children, opts)

# Or directly initialize the GenServer
{:ok,_} = Statsig.start_link(sdk_key, statsig_options)
Statsig.initialize()
    initialize performs a network request. After initialize completes, virtually all SDK operations are synchronous (refer to Evaluating Feature Gates in the Statsig SDK). The SDK fetches updates from Statsig in the background, independent of your API calls.

Working with the SDK

Checking a Feature Flag/Gate

After the SDK is initialized, you can fetch a Feature Gate. Feature Gates create logic branches in code that you can roll out to different users from the Statsig Console. Gates are CLOSED or OFF (equivalent to return false;) by default.All APIs require a user object (refer to Statsig user). To check a gate for a user:
elixir
user = %StatsigUser{
    user_id: "test_user_123"
}

{:ok, check_gate} = Statsig.check_gate("test_public", user)
# check_gate will be a boolean

Reading a Dynamic Config

Feature Gates are useful for simple on/off switches with optional user targeting. To send different values (strings, numbers, etc.) to clients based on user attributes such as country, use Dynamic Configs. The API is similar to Feature Gates, but returns a JSON object from which you can retrieve typed parameters. For example:
elixir
# Get a dynamic config for a specific user
user = %StatsigUser{
    user_id: "test_user_123"
}
{:ok, config} = Statsig.get_dynamic_config("a_config", user)

# Access the values in the dynamic config:

param_value = DynamicConfig.get_param_value(config, "header_text")

# Disable exposure
options = %Statsig.DynamicConfigEvaluationOptions{
    disable_exposure_logging = true
}
{:ok, config} = Statsig.get_dynamic_config("a_config", user, options)

Getting a Layer/Experiment

Layers/Experiments let you run A/B/n experiments. Two APIs are available, but layers are recommended because layers make parameters reusable and support mutually exclusive experiments.
elixir
# Values via get_layer
user = %StatsigUser{
    user_id: "test_user_123"
}

{:ok, layer} = Statsig.get_layer("user_promo_experiments", user)
{:ok, title_string_value} = Layer.get(layer, "title", "Welcome to Statsig!")
{:ok, discount_float_value} = Layer.get(layer, "discount", 0.1)

# Via get_experiment
{:ok, experiment} = Statsig.get_experiment("user_promo_experiment", user)
title_exp = Experiment.get_param_value(experiment, "new_user_promo_title")

# Disable exposure
options = %Statsig.ExperimentEvaluationOptions{
    disable_exposure_logging = true
}
{:ok, experiment} = Statsig.get_experiment("user_promo_experiment", user, options)

If you are using layer to get value -- get param value. It will return primitive types: boolean, string, and numbers, for more complex type, SDK will return json serialized values.

Retrieving Feature Gate Metadata

To retrieve more information about a gate evaluation than a boolean value, use the Get Feature Gate API, which returns a FeatureGate object:

elixir
{:ok, feature_gate} = Statsig.get_feature_gate(user, "example_gate")
# access the value, or the name off of the feature_gate object

options = %Statsig.FeatureGateEvaluationOptions{
    disable_exposure_logging = true
}
{:ok, feature_gate} = Statsig.get_feature_gate(user, "example_gate", options)

Parameter Stores

If you want dynamic control over whether a value comes from a Feature Gate, Experiment, or Dynamic Config outside your deployment cycle, use Parameter Stores. A Parameter Store lets you define a parameter that you can change at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application supports future flexibility and allows non-technical Statsig users to turn parameters into experiments.

Parameter stores are not yet available for this sdk. Need it now? Let us know in Slack.

Logging an Event

After setting up a Feature Gate or Experiment, track custom events to measure how features or experiment groups affect user behavior. Call the Log Event API and specify the user and event name. You can also provide a value and metadata:

elixir
Statsig.log_event(user, "test_event", 1, %{"metadata_1" => "value"})

Sending events to Log Explorer

You can forward logs to Logs Explorer for analysis using the Forward Log Line Event API. This lets you include custom metadata and event values with each log.

Sending events to Log Explorer is not yet available for this sdk. Need it now? Let us know in Slack.

Statsig User

The StatsigUser object represents a user in Statsig. You must provide a userID or at least one of the customIDs to identify the user.

When calling APIs that require a user, pass as much information as possible to enable advanced gate and config conditions (such as country or OS/browser checks) and to measure experiment impact accurately. As explained in why an ID is always required for server SDKs, at least one identifier (userID or customID) is required to provide a consistent experience for a given user.

In addition to userID, the top-level fields on StatsigUser are: email, ip, userAgent, country, locale, and appVersion. You can also pass key-value pairs in the custom field for targeting.

Private attributes

Private attributes are user attributes used for evaluation but not forwarded to any integrations. Use them for PII or sensitive data that you don't want to send to third-party services.

elixir
user = %Statsig.User{
  user_id: "a-user-id",
  email: "user@example.com",
  ip: "192.168.1.1",
  user_agent: "Mozilla/5.0...",
  country: "US",
  locale: "en_US",
  app_version: "1.0.0",
  custom: %{
    # Custom fields
    "plan" => "premium",
    "age" => 25
  },
  custom_ids: %{
    # Custom ID types
    "stable_id" => "stable-id-123"
  },
  private_attributes: %{
    # Private attributes not forwarded to integrations
    "email" => "private@example.com"
  }
}

Statsig Options

You can pass an optional options parameter in addition to sdkKey during initialization to customize the Statsig client.

Proxy and Custom Network Routing

The Elixir Server Core SDK doesn't currently document a dedicated outbound HTTP proxy config. For custom network routing, use spec_adapter_configs for Statsig Forward Proxy or set specs_url, log_event_url, and id_lists_url directly.
elixir
statsig_options = %StatsigOptions{
  spec_adapter_configs: [
    %Statsig.SpecAdapterConfig{
      adapter_type: "network_grpc_websocket",
      specs_url: "http://forward-proxy.internal:50051",
      authentication_mode: "none"
    }
  ],
  fallback_to_statsig_api: true
}

Shutting Statsig Down

Because events are batched and periodically flushed, some events may not have been sent when your app or server shuts down. To ensure all logged events are flushed, call shutdown() before your app or server shuts down:

elixir
Statsig.shutdown()

Client SDK Bootstrapping | SSR

If you are using the Statsig client SDK in a browser or mobile app, you can bootstrap the client SDK with values from the server SDK to avoid a network request on the client. This is useful for server-side rendering (SSR) or when you want to reduce the number of network requests on the client.

elixir
# Get client initialize response for a user
{:ok, response} = Statsig.get_client_init_response_as_string(user)

# Pass values to a client SDK to initialize without a network request

Persistent storage

The Persistent Storage interface lets you implement custom storage for user-specific configurations. Use it to persist user assignments across sessions, ensuring consistent experiment groups when users return. This is useful for client-side A/B testing where users must always see the same variant.

Not supported at this time.

Data store

The Data Store interface lets you implement custom storage for Statsig configurations, enabling advanced caching strategies and integration with your preferred storage systems.

Not supported at this time.

Custom output logger

The Output Logger interface lets you customize how the SDK logs messages, enabling integration with your own logging system and control over log verbosity.

Not supported at this time.

Observability client

The Observability Client interface lets you monitor SDK health by integrating with your own observability systems, enabling tracking of metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, go to the Monitoring documentation.

Not supported at this time.

FAQ

Was this helpful?