***

title: Go
'og:site\_name': Unleash
'og:title': Go SDK
description: Go SDK for integrating with Unleash feature management platform
keywords:

* unleash
* go
* sdk
* feature flags
* feature toggles
* golang
  max-toc-depth: 3

***

This Backend Go SDK is designed to help you integrate with Unleash and evaluate feature flags inside your application.

You can use this client with [Unleash Enterprise](https://www.getunleash.io/pricing?utm_source=readme\&utm_medium=go) or [Unleash Open Source](https://github.com/Unleash/unleash).

## Go Version

The client is currently tested against Go 1.21.x, 1.22.x, 1.23.x and 1.24.x. These versions will be updated
as new versions of Go are released.

The client may work on older versions of Go as well, but is not actively tested.

## Getting Started

### 1. Install unleash-go-sdk

To install the latest version of the client use:

```bash
go get github.com/Unleash/unleash-go-sdk/v5
```

### 2. Initialize unleash

The easiest way to get started with Unleash is to initialize it early in your application code:

**Asynchronous initialization example:**

```go
import (
	"github.com/Unleash/unleash-go-sdk/v5"
)

func init() {
	unleash.Initialize(
		unleash.WithListener(&unleash.DebugListener{}),
		unleash.WithAppName("my-application"),
		unleash.WithUrl("https://eu.app.unleash-hosted.com/demo/api/"),
		unleash.WithCustomHeaders(http.Header{"Authorization": {"<API token>"}}),
	)
}
```

**Synchronous initialization example:**

```go
import (
	"github.com/Unleash/unleash-go-sdk/v5"
)

func init() {
	unleash.Initialize(
		unleash.WithListener(&unleash.DebugListener{}),
		unleash.WithAppName("my-application"),
		unleash.WithUrl("https://eu.app.unleash-hosted.com/demo/api/"),
		unleash.WithCustomHeaders(http.Header{"Authorization": {"<API token>"}}),
	)

	// Note this will block until the default client is ready
	unleash.WaitForReady()
}
```

#### Preloading Feature Toggles

If you'd like to prebake your application with feature toggles (maybe you're working without persistent storage, so Unleash's backup isn't available), you can replace the defaultStorage implementation with a BootstrapStorage. This allows you to pass in a reader to where data in the format of `/api/client/features` can be found.

#### Bootstrapping From File

Bootstrapping from file on disk is then done using something similar to:

```go
import (
	"github.com/Unleash/unleash-go-sdk/v5"
)

func init() {
	myBootstrap := os.Open("bootstrapfile.json") // or wherever your file is located at runtime
	// BootstrapStorage handles the case where Reader is nil
	unleash.Initialize(
		unleash.WithListener(&unleash.DebugListener{}),
		unleash.WithAppName("my-application"),
		unleash.WithUrl("https://eu.app.unleash-hosted.com/demo/api/"),
		unleash.WithStorage(&BootstrapStorage{Reader: myBootstrap})
	)
}
```

#### Bootstrapping From S3

Bootstrapping from S3 is then done by downloading the file using the AWS library and then passing in a Reader to the just downloaded file:

```go
import (
	"github.com/Unleash/unleash-go-sdk/v5"
	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/s3"
)

func init() {
	// Load the shared AWS config
	cfg, err := config.LoadDefaultConfig(context.TODO())
	if err != nil {
		log.Fatal(err)
	}

	// Create an S3 client
	client := s3.NewFromConfig(cfg)

	obj, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
		Bucket: aws.String("YOURBUCKET"),
		Key:    aws.String("YOURKEY"),
	})

	if err != nil {
		log.Fatal(err)
	}

	reader := obj.Body
	defer reader.Close()

	// BootstrapStorage handles the case where Reader is nil
	unleash.Initialize(
		unleash.WithListener(&unleash.DebugListener{}),
		unleash.WithAppName("YOURAPPNAME"),
		unleash.WithUrl("YOURINSTANCE_URL"),
		unleash.WithStorage(&BootstrapStorage{Reader: reader})
	)
}
```

#### Bootstrapping From Google

Since the Google Cloud Storage API returns a Reader, implementing a Bootstrap from GCS is done using something similar to

```go
import (
	"github.com/Unleash/unleash-go-sdk/v5"
	"cloud.google.com/go/storage"
)

func init() {
	ctx := context.Background() // Configure Google Cloud context
	client, err := storage.NewClient(ctx) // Configure your client
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()

	// Fetch the bucket, then object and then create a reader
	reader := client.Bucket(bucketName).Object("my-bootstrap.json").NewReader(ctx)

	// BootstrapStorage handles the case where Reader is nil
	unleash.Initialize(
		unleash.WithListener(&unleash.DebugListener{}),
		unleash.WithAppName("my-application"),
		unleash.WithUrl("https://eu.app.unleash-hosted.com/demo/api/"),
		unleash.WithStorage(&unleash.BootstrapStorage{Reader: reader})
	)
}
```

### 3. Use unleash

After you have initialized the unleash-client you can easily check if a feature
toggle is enabled or not.

```go
unleash.IsEnabled("app.ToggleX")
```

### 4. Stop unleash

To shut down the client (turn off the polling) you can simply call the
destroy-method. This is typically not required.

unleash.Close()

### Built in Activation Strategies

The Go client comes with implementations for the built-in activation strategies
provided by unleash.

* DefaultStrategy
* UserIdStrategy
* FlexibleRolloutStrategy
* GradualRolloutUserIdStrategy
* GradualRolloutSessionIdStrategy
* GradualRolloutRandomStrategy
* RemoteAddressStrategy
* ApplicationHostnameStrategy

[Read more about activation strategies in the docs](/concepts/activation-strategies).

### Unleash Context

In order to use some of the common activation strategies you must provide an
[unleash-context](/concepts/unleash-context).
This client SDK allows you to send in the unleash context as part of the `isEnabled` call:

```go
ctx := context.Context{
	UserId:        "123",
	SessionId:     "some-session-id",
	RemoteAddress: "127.0.0.1",
}

unleash.IsEnabled("someToggle", unleash.WithContext(ctx))
```

### Caveat

This client uses go routines to report several events and doesn't drain the channel by default. So you need to either register a listener using `WithListener` or drain the channel "manually" (demonstrated in [this example](https://github.com/Unleash/unleash-go-sdk/blob/v5/example_with_instance_test.go)).

### Feature Resolver

`FeatureResolver` is a `FeatureOption` used in `IsEnabled` via the `WithResolver`.

The `FeatureResolver` can be used to provide a feature instance in a different way than the client would normally retrieve it. This alternative resolver can be useful if you already have the feature instance and don't want to incur the cost to retrieve it from the repository.

An example of its usage is below:

```go
ctx := context.Context{
	UserId:        "123",
	SessionId:     "some-session-id",
	RemoteAddress: "127.0.0.1",
}

// the FeatureResolver function that will be passed into WithResolver
resolver := func(featureName string) *api.Feature {
    if featureName == "someToggle" {
        // Feature being created in place for sake of example, but it is preferable an existing feature instance is used
        return &api.Feature{
            Name:        "someToggle",
            Description: "Example of someToggle",
            Enabled:     true,
            Strategies: []api.Strategy{
                {
                    Id:   1,
                    Name: "default",
                },
            },
            CreatedAt:  time.Time{},
            Strategy:   "default-strategy",
        }
    } else {
        // it shouldn't reach this block because the name will match above "someToggle" for this example
        return nil
    }
}

// This would return true because the matched strategy is default and the feature is Enabled
unleash.IsEnabled("someToggle", unleash.WithContext(ctx), unleash.WithResolver(resolver))
```

### Impression Data

When impression data is enabled on a flag, the SDK will emit impression events during evaluation. You can hook into these with a custom listener to collect insights or integrate with analytics. You can [read more about impression data in Unleash's documentation](/concepts/impression-data).

```go
type MyListener struct {
	unleash.DebugListener
}

func (l *MyListener) OnImpression(e unleash.ImpressionEvent) {
	fmt.Printf("Custom Impression: %s = %v (%s)\n", e.FeatureName, e.Enabled, e.EventType)
	if e.Context != nil {
		fmt.Printf("Context: userId=%s sessionId=%s\n", e.Context.UserId, e.Context.SessionId)
	}
}

func main() {
	unleash.Initialize(
		unleash.WithListener(&MyListener{}),
		unleash.WithAppName("my-app"),
		unleash.WithUrl("https://eu.app.unleash-hosted.com/demo/api/"),
	)
}
```

## Development

To override dependency on unleash-go-sdk github repository to a local development folder (for instance when building a local test-app for the SDK),
you can add the following to your apps `go.mod`:

```mod
    replace github.com/Unleash/unleash-go-sdk/v5 => ../unleash-go-sdk/
```

## Steps to Release

* Update the clientVersion in `client.go`
* Tag the repository with the new tag
* Create the release manually in Github

## Adding Client Specifications

In order to make sure the unleash clients uphold their contract, we have defined a set of
client specifications that define this contract. These are used to make sure that each unleash client
at any time adhere to the contract, and define a set of functionality that is core to unleash. You can view
the [client specifications here](https://github.com/Unleash/client-specification).

In order to make the tests run please do the following steps.

```
// in repository root
// testdata is gitignored
mkdir testdata
cd testdata
git clone https://github.com/Unleash/client-specification.git
```

Requirements:

* make
* golint (go get -u golang.org/x/lint/golint)

Run tests:

make

Run lint check:

make lint

Run code-style checks:(currently failing)

make strict-check

Run race-tests:

make test-race

## Benchmarking

You can benchmark feature toggle evaluation by running:

```
go test -run=^$ -bench=BenchmarkFeatureToggleEvaluation -benchtime=10s
```

Here's an example of how the output could look like:

```
goos: darwin
goarch: arm64
pkg: github.com/Unleash/unleash-go-sdk/v5
BenchmarkFeatureToggleEvaluation-8 Final Estimated Operations Per Day: 101.131 billion (1.011315e+11)
13635154 854.3 ns/op
PASS
ok github.com/Unleash/unleash-go-sdk/v5 13.388s
```

In this example the benchmark was run on a MacBook Pro (M1 Pro, 2021) with 16GB RAM.

We can see a result of **854.3 ns/op**, which means around **101.131 billion** feature toggle evaluations per day.

**Note**: The benchmark is run with a single CPU core, no parallelism.

## Design Philosophy

This feature flag SDK is designed according to our design philosophy. You can [read more about that here](/guides/feature-flag-best-practices).