This feature is in Early Access. During this time, aspects of the functionality may still be developed, and this documentation may not always be up to date. If you have any questions, contact Statsig Support.
Setup the SDK
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
Always keep Server Secret Keys 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 StatsigOptionssdk_key = "secret-key******" # your secret keystatsig_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 you initialize the SDK, 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 useruser = %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 exposureoptions = %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 Statsig recommends layers because layers make parameters reusable and support mutually exclusive experiments.
When you use a layer to get a value, use get param value. This method returns primitive types (boolean, string, and numbers). For more complex types, the SDK returns 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 objectoptions = %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? Reach out 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:
You can forward logs to Logs Explorer for analysis using the Forward Log Line Event API. The API 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? Reach out 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. More user attributes enable advanced gate and config conditions (such as country or OS/browser checks) and more accurate experiment impact measurement. You must provide at least one identifier (userID or customID) to ensure a consistent experience for a given user. For details, refer to why an ID is always required for server SDKs.
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 that Statsig uses for evaluation but doesn't forward to any integrations. Use them for PII or sensitive data that you don't want to send to third-party services.
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 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.
Because the SDK batches events and periodically flushes them, some events might not send before your app or server shuts down. To flush all logged events, 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. Bootstrapping 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. Persistent storage is useful for client-side A/B testing where users must always see the same variant.
Not supported yet.
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 yet.
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 yet.
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.