Skip to main content
Go Core on Github

​
Setup the SDK

1

Install the SDK

via the go get CLI:You can install the latest version of the SDK:
go get github.com/statsig-io/statsig-server-core/statsig-go@latest
or a specific version of the SDK:
go get github.com/statsig-io/statsig-server-core/statsig-go@v0.7.2
Or, add a dependency on the most recent version of the SDK in go.mod:
require (
  github.com/statsig-io/statsig-server-core/statsig-go v0.7.2
)
See the Releases tab in GitHub for the latest versions.:::note Running go get will only work if you’re working inside a module project with a go.mod file. If working outside of a module project, you can clone the repo here: https://github.com/statsig-io/statsig-server-core/tree/main/statsig-go instead. :::Run the following commands to install the necessary binaries and set environment variables:
go install github.com/statsig-io/statsig-server-core/statsig-go/cmd/post-install@latest

// Run the following commands based on your OS:
// macOS:
export PATH="$PATH:$(go env GOPATH)/bin"
source ~/.zshrc

// Linux:
export PATH="$PATH:$(go env GOPATH)/bin"
source ~/.bashrc

// Windows (PowerShell):
$env:PATH += ";$env:USERPROFILE\.statsig\bin"

post-install
The system should prompt you to set the environment variables using a statsig.env or statsig.env.ps1 file that was generated during the post-install script. Follow the instructions to set the environment variables.
// E.g. - the command will look something like this:

macOS: 
source /Users/Your-User-Name/.statsig_env

Windows (PowerShell): 
. "C:\Users\Your-User-Name\.statsig_env.ps1"
Users can also add in the variables to their .bashrc, .zshrc, or .ps1 file to load them automatically.:::note You may need to have gcc installed on your system in order to run the SDK on Windows.See FAQ if you run into any issues with installation.
2

Initialize the SDK

After installation, you will need to 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.
There is also an optional parameter named options that allows you to pass in a StatsigOptions to customize the SDK.
import (
    statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)
			
options := statsig.NewStatsigOptionsBuilder().WithOutputLogLevel("DEBUG").Build()
s, err := statsig.NewStatsig("secret-key", *options)

if err != nil {
    // Initialize the SDK with the secret key and options
    s.Initialize()
}

// Or if you want to initialize the Statsig client with more details
details, err := s.InitializeWithDetails()

json, err := json.MarshalIndent(details, "", " ")
fmt.Println("Initialize With Details:", string(json))

/*
*** Sample Output ***
Initialize With Details: {
 "duration": 95,
 "init_success": true,
 "is_config_spec_ready": true,
 "is_id_list_ready": null,
 "source": "Network",
 "failure_details": null
}
*/
initialize will perform a network request. After initialize completes, virtually all SDK operations will be synchronous (See Evaluating Feature Gates in the Statsig SDK). The SDK will fetch updates from Statsig in the background, independently of your API calls.

​
Working with the SDK

​
Checking a Feature Flag/Gate

Now that your SDK is initialized, let’s fetch a Feature Gate. Feature Gates can be used to create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always CLOSED or OFF (think return false;) by default. From this point on, all APIs will require you to specify the user (see Statsig user) associated with the request. For example, check a gate for a certain user like this: 
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()

if s.CheckGate(*user, "a_gate", nil) {
    // Gate is on, enable new feature
} else {
    // Gate is off
}

​
Reading a Dynamic Config

Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, Dynamic Configs can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example: 
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()

// You can disable exposure logging for this specific check
dynamicConfigOptions := &statsig.GetDynamicConfigOptions{DisableExposureLogging: false}

dynamic_config := "a_config"
config := s.GetDynamicConfig(*user, dynamic_config, dynamicConfigOptions)

// Access the config values
str_val := config.GetString("str_val", "default_str_val") // returns String
int_val := config.GetNumber("number_val", 100) // returns float64
bool_val := config.GetBool("bool_val", false) // returns bool
interface_val := config.GetSlice("interface_val", "default_interface_val") // returns interface{}
map_val := config.GetMap("map_val", "default_map_val") // returns map[string]interface{}

// The config object also provides metadata about the evaluation
fmt.Println(config.RuleID) // The ID of the rule that served this config
fmt.Println(config.IDType) // The type of the evaluation (experiment, config, etc)

​
Getting a Layer/Experiment

Then we have Layers/Experiments, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of layers, which make parameters reusable and let you run mutually exclusive experiments. 
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()

// Getting values with GetExperiment
experimentOptions := &statsig.GetExperimentOptions{DisableExposureLogging: false}

experiment := s.GetExperiment(*user, "a_test_experiment", experimentOptions)
str_val := experiment.GetString("str_val", "default_str_val") // returns String
int_val := experiment.GetNumber("number_val", 100) // returns float64

// Getting values with GetLayer
layerOptions := &statsig.GetLayerOptions{DisableExposureLogging: false}

layer := s.GetLayer(user, "a_test_experiment", layerOptions)
str_val := layer.GetString("str_val", "default_str_val") // returns String
int_val := layer.GetNumber("number_val", 100) // returns float64

​
Retrieving Feature Gate Metadata

In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object: 
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()

checkGateOptions := &statsig.CheckGateOptions{DisableExposureLogging: false}
featureGate := s.GetFeatureGate(*user, "a gate", checkGateOptions)

​
Parameter Stores

Sometimes you don’t know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.

​
Getting a Parameter Store

// Get a Parameter Store by name

s, _ := statsig.NewStatsig("secret-key", options)

user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()
options := statsig.ParameterStoreOptions{DisableExposureLogging: false}

paramStore := s.GetParameterStore(*user, "paramStore", &options)

​
Retrieving Parameter Values

Parameter Store provides methods for retrieving values of different types with fallback defaults. 
//String parameters
stringVal := paramStore.GetString("str_param", "default_value")

//Boolean parameters
boolVal := paramStore.GetBoolean("bool_param", false)

//Numeric parameters
intVal := paramStore.GetInt("int_param", 0)
int64Val := paramStore.GetInt64("int64_param", 0)
float64Val := paramStore.GetFloat64("float64_param", 0.0)

//Complex parameters
objectParam := map[string]interface{}{
    "value1": "string",
    "value2": 1,
    "value3": 1.0,
}
objectVal := paramStore.GetMap("obj_param", objectParam)

arrayParam := []interface{}{"val1", "val2", "val3"}
arrayVal := paramStore.GetInterface("array_param", arrayParam)

​
Evaluation Options

You can disable exposure logging when retrieving a parameter store: 
options := statsig.ParameterStoreOptions{DisableExposureLogging: false}
paramStore := s.GetParameterStore(*user, "param_store", &options)

​
Logging an Event

Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event: 
event := map[string]interface{}{
		"name":  "sample event",
		"value": "event",
		"metadata": map[string]string{
			"val_1": "log val 1",
		},
	}


user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()
s.LogEvent(*user, event)

​
Manual Exposures

By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or get a layer. However, there are times when you may want to log an exposure event manually. For example, if you’re using a gate to control access to a feature, but you don’t want to log an exposure until the user actually uses the feature, you can use manual exposures. All of the main SDK functions (CheckGate, GetDynamicConfig, GetExperiment, GetLayer) accept an optional options parameter with DisableExposureLogging field. When this is set to true, the SDK will not automatically log an exposure event. You can then manually log the exposure at a later time using the corresponding manual exposure logging method:
  • Feature Gates
  • Dynamic Configs
  • Experiments
  • Layers
result := statsig.CheckGate(aUser, "a_gate_name", statsig.CheckGateOptions{DisableExposureLogging: true})

statsig.ManuallyLogGateExposure(aUser, "gate_name")

​
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, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. At least one ID (userID or customID) is required because it’s needed to provide a consistent experience for a given user (click here) Besides userID, we also have email, ip, userAgent, country, locale and appVersion as top-level fields on StatsigUser. In addition, you can pass any key-value pairs in an object/dictionary to the custom field and be able to create targeting based on them.

​
Private Attributes

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

​
Statsig Options

You can pass in an optional parameter options in addition to sdkKey during initialization to customize the Statsig client. Here are the available options that you can configure.

​
Parameters

​
SpecsUrl
string
Custom URL for fetching feature specifications.
​
LogEventUrl
string
Custom URL for logging events.
​
Environment
string
Environment parameter for evaluation.
​
EventLoggingFlushIntervalMs
number
How often events are flushed to Statsig servers (in milliseconds).
​
EventLoggingMaxQueueSize
number
Maximum number of events to queue before forcing a flush.
​
SpecsSyncIntervalMs
number
How often the SDK updates specifications from Statsig servers (in milliseconds).
​
OutputLogLevel
string
Controls the verbosity of SDK logs.
​
DisableCountryLookup
boolean
Disables country lookup based on IP address. Set to true to improve performance if country-based targeting is not needed.
​
DisableUserAgentParsing
boolean
Disables user agent parsing. Set to true to improve performance if device/browser-based targeting is not needed.
​
WaitForCountryLookupInit
boolean
default:"false"
When set to true, the SDK will wait for country lookup data (e.g., GeoIP or YAML files) to fully load during initialization. This may slow down by ~1 second startup but ensures that IP-to-country parsing is ready at evaluation time.
​
WaitForUserAgentInit
boolean
default:"false"
When set to true, the SDK will wait until user agent parsing data is fully loaded during initialization. This may slow down by ~1 second startup but ensures that parsing of the user’s userAgent string into fields like browserName, browserVersion, systemName, systemVersion, and appVersion is ready before any evaluations.
​
DisableAllLogging
boolean
default:"false"
When set to true, the SDK will not log any events or exposures.
​
InitTimeoutMs
number
default:"3000"
Maximum time in milliseconds to wait for SDK initialization to complete. If initialization takes longer than this timeout, the SDK will continue to operate but may return default values until initialization completes.
​
FallbackToStatsigApi
boolean
default:"false"
When set to true, the SDK will fallback to using the Statsig API directly if custom adapters (like local file adapters) fail to load configurations.

​
Example Options Usage

import (
    statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)

// Initialize StatsigOptions with custom parameters
options := statsig.NewStatsigOptionsBuilder().
		WithSpecsUrl("https://example.com/specsUrl").
		WithLogEventUrl("https://example.com/logUrl").
		WithEnvironment("production").
		WithEventLoggingFlushIntervalMs(2000).
		WithEventLoggingMaxQueueSize(5000).
		WithSpecsSyncIntervalMs(1000).
		WithOutputLogLevel("DEBUG").
		WithDisableCountryLookup(true).
		WithDisableUserAgentParsing(true).
		WithWaitForCountryLookupInit(false).
		WithInitTimeoutMs(3000).
		WithFallbackToStatsigApi(false).
		Build()

// Pass the options object when initializing the Statsig client
s, err := statsig.NewStatsig("secret-key", *options)
s.Initialize()

​
Shutting Statsig Down

Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call shutdown() before your app/server shuts down: 
// Method signature
func (s *Statsig) Shutdown() {}

// example usage
s, err := statsig.NewStatsig("secret-key", statsig.StatsigOptions{})
s.Shutdown()

​
Flush Events

// Method signature
func (s *Statsig) FlushEvents() {}

// example usage
s, err := statsig.NewStatsig("secret-key", statsig.StatsigOptions{})
s.FlushEvents()

​
Local Overrides

Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console. 
import (
    statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)

options := statsig.NewStatsigOptionsBuilder().WithOutputLogLevel("DEBUG").Build()
s, _ := statsig.NewStatsig("secret-key", *options)

s.OverrideLayer("layer_name", map[string]interface{}{"key": "value"}, "test-user-id")
s.OverrideGate("gate_name", true, "test-user-id")
s.OverrideDynamicConfig("config_name", map[string]interface{}{"key": "value"}, "test-user-id")
s.OverrideExperiment("experiment_name", map[string]interface{}{"key": "value"}, "test-user-id")
s.OverrideExperimentByGroupName("experiment_name", "group_name", "test-user-id")

​
FAQ

Installation FAQs

​
How do I fix undefined symbol errors/linker errors?

You may need to reset your environment variables to those found in the statsig.env or statsig.env.ps1 file which was generated during the post-install script. Running the command sets the environment variables for the current terminal session. Users may need to add in the variables to their .bashrc, .zshrc, or .ps1 file to load them automatically.
⌘I