Experiment Go SDK

Official documentation for Amplitude Experiment's server-side Go SDK implementation.

This documentation is split into two sections for remote and local evaluation:

Remote evaluation

Implements fetching variants for a user via remote evaluation.

Install

Install the Go Server SDK using go get.

1go get github.com/amplitude/experiment-go-server

 1// (1) Initialize the local evaluation client with a server deployment key.
 2client := remote.Initialize("<DEPLOYMENT_KEY>", nil)
 3 
 4// (2) Fetch variants for a user
 5user := &experiment.User{
 6  UserId:   "user@company.com",
 7  DeviceId: "abcdefg",
 8  UserProperties: map[string]interface{}{
 9    "premium": true,
10  },
11}
12variants, err := client.Fetch(user)
13if err != nil {
14  // Handle error
15}
16 
17// (3) Access a flag's variant
18variant := variants["<FLAG_KEY>"]
19if variant.Value == "on" {
20    // Flag is on
21} else {
22    // Flag is off
23}

Initialize

The SDK client should be initialized in your server on startup. The deployment key argument passed into the apiKey parameter must live within the same project that you are sending analytics events to.

1func Initialize(apiKey string, config *Config) *Client

1client := remote.Initialize("<DEPLOYMENT_KEY>", nil)

Configuration

The SDK client can be configured on initialization.

Fetch

Fetches variants for a user and returns the results. This function remote evaluates the user for flags associated with the deployment used to initialize the SDK client.

1func (c *Client) Fetch(user *experiment.User) (map[string]experiment.Variant, error)

 1user := &experiment.User{
 2    UserId:   "user@company.com",
 3    DeviceId: "abcdefg",
 4    UserProperties: map[string]interface{}{
 5        "premium": true,
 6    },
 7}
 8variants, err := client.Fetch(user)
 9if err != nil {
10    // Handle error
11}

After fetching variants for a user, you may to access the variant for a specific flag.

1variant := variants["<FLAG_KEY>"]
2if variant.Value == "on" {
3    // Flag is on
4} else {
5    // Flag is off
6}

Local evaluation

Implements evaluating variants for a user via local evaluation. If you plan on using local evaluation, you should understand the tradeoffs.

Install

Install the Go Server SDK using go get.

1go get github.com/amplitude/experiment-go-server

 1// (1) Initialize the local evaluation client with a server deployment key.
 2client := local.Initialize("<DEPLOYMENT_KEY>", &local.Config{
 3 // (Recommended) Enable local evaluation cohort targeting.
 4 CohortSyncConfig: &local.CohortSyncConfig {
 5   ApiKey: "<API_KEY>",
 6   SecretKey: "<SECRET_KEY>"
 7 }
 8})
 9 
10// (2) Start the local evaluation client.
11err := client.Start()
12if err != nil {
13  panic(err)
14}
15 
16  // (3) Evaluate a user.
17user := &experiment.User{DeviceId: "abcdefg"}
18variants, err := client.EvaluateV2(user, nil)
19if err != nil {
20  panic(err)
21}

Initialize

Initializes a local evaluation client.

1func Initialize(apiKey string, config *Config) *Client

Configuration

The SDK client can be configured on initialization.

Config

AssignmentConfig

CohortSyncConfig

Start

Start the local evaluation client, pre-fetching local evaluation mode flag configs for evaluation and starting the flag config poller at the configured interval.

1func (c *Client) Start() error

You should await the result of Start() to ensure that flag configs are ready to be used before calling Evaluate()

1err := client.Start()
2if err != nil {
3    panic(err)
4}

Evaluate

Executes the evaluation logic using the flags pre-fetched on Start(). Evaluate must be given a user object argument and can optionally be passed an array of flag keys if only a specific subset of required flag variants are required.

1func (c *Client) EvaluateV2(user *experiment.User, flagKeys []string) (map[string]experiment.Variant, error)

 1// The user to evaluate
 2user := &experiment.User{DeviceId: "abcdefg"}
 3 
 4// Evaluate all flag variants
 5allVariants, err := client.EvaluateV2(user, nil)
 6if err != nil {
 7    // Handle Error
 8}
 9 
10// Evaluate a specific subset of flag variants
11specificVariants, err := client.EvaluateV2(user, []string{
12    "<FLAG_KEY_1>",
13    "<FLAG_KEY_2>",
14})
15 
16// Access a variant
17variant := allVariants["<FLAG_KEY>"]
18if variant.Value == "on" {
19    // Flag is on
20} else {
21    // Flag is off
22}

Local evaluation cohort targeting

Since version 1.7.0, the local evaluation SDK client supports downloading cohorts for local evaluation targeting. Configure the CohortSyncConfig option with the analytics ApiKey and SecretKey on initialization to enable this support.

1client := local.Initialize("<DEPLOYMENT_KEY>", &local.Config{
2  // (Recommended) Enable local evaluation cohort targeting.
3  CohortSyncConfig: &local.CohortSyncConfig {
4    ApiKey: "<API_KEY>",
5    SecretKey: "<SECRET_KEY>"
6  }
7})