growthbook

package module
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 8, 2025 License: MIT Imports: 23 Imported by: 6

README

GrowthBook Go SDK

GrowthBook is a modular feature flagging and experimentation platform.

This is the Go client library that lets you evaluate feature flags and run experiments (A/B tests) within a Go application.

Requirements

  • Go version 1.21 or higher (tested with 1.21, 1.22, and 1.23)

Installation

go get github.com/growthbook/growthbook-golang

Usage

Quick Start
import (
    "context"
    "log"
    gb "github.com/growthbook/growthbook-golang"
)

// Create a new client instance with a client key and 
// a data source that loads features in the background via SSE stream.
// Pass the client's options to the NewClient function.
client, err := gb.NewClient(
    context.Background(),
    gb.WithClientKey("sdk-XXXX"),
    gb.WithSseDataSource(),
) 
defer client.Close()

if err != nil {
    log.Fatal("Client initialization failed: ", err)
}

// The data source starts asynchronously. Use EnsureLoaded to 
// wait until the client data is initialized for the first time.
if err := client.EnsureLoaded(context.Background()); err != nil {
    log.Fatal("Data loading failed: ", err)
}

// Create a child client with specific attributes.
attrs := gb.Attributes{"id": 100, "user": "user1"}
child, err := client.WithAttributes(attrs)
if err != nil {
    log.Fatal("Child client creation failed: ", err)
}

// Evaluate a text feature
buttonColor := child.EvalFeature(context.Background(), "buy-button-color")
if buttonColor.Value == "blue" {
    // Perform actions for blue button
}

// Evaluate a boolean feature
darkMode := child.EvalFeature(context.Background(), "dark-mode")
if darkMode.On {
    // Enable dark mode
}
Client

The client is the core component of the GrowthBook SDK. After installing and importing the SDK, create a single shared instance of growthbook.Client using the growthbook.NewClient function with a list of options. You can customize the client with options like a custom logger, client key, decryption key, default attributes, or a feature list from JSON. The client is thread-safe and can be safely used from multiple goroutines.

While you can evaluate features directly using the main client instance, it’s recommended to create child client instances that include session- or query-specific data. To create a child client with local attributes, call client.WithAttributes:

attrs := gb.Attributes{"id": 100, "user": "Bob"}
child, err := client.WithAttributes(attrs)

Now, you can evaluate features using the child client:

res := child.EvalFeature(context.Background(), "main-button-color")

Additional options, such as WithLogger, WithUrl, and WithAttributesOverrides, can also be used to customize child clients. Since child clients share data with the main client instance, they will automatically receive feature updates.

To stop background updates, call client.Close() on the main client instance when it is no longer needed.

Tracking

You can set up two callbacks to track experiment results and feature usage in your analytics or event tracking system:

  1. ExperimentCallback: Triggered when a user is included in an experiment.
  2. FeatureUsageCallback: Triggered on each feature evaluation.

You can also attach extra data that will be sent with each callback. These callbacks can be set globally via the NewClient function using the WithExperimentCallback and WithFeatureUsageCallback options. Alternatively, you can set them locally when creating child clients using similar methods like client.WithExperimentCallback. Extra data is set via the WithExtraData option.

Documentation

Documentation

Overview

Package growthbook is the GrowthBook Go client library. It enables you to seamlessly evaluate feature flags and conduct A/B testing (experiments) directly within your Go application, integrating with the GrowthBook platform.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrCryptoInvalidEncryptedFormat = errors.New("Crypto: encrypted data is in invalid format")
	ErrCryptoInvalidIVLength        = errors.New("Crypto: invalid IV length")
	ErrCryptoInvalidPadding         = errors.New("Crypto: invalid padding")
)
View Source 
var (
	ErrNoDecryptionKey = errors.New("No decryption key provided")
)

Functions

This section is empty.

Types

type Attributes 

type Attributes map[string]any

type BucketRange added in v0.2.0 

type BucketRange struct {
	Min float64
	Max float64
}

BucketRange represents a single bucket range.

func (*BucketRange) InRange added in v0.2.0 

func (r *BucketRange) InRange(n float64) bool

func (*BucketRange) UnmarshalJSON added in v0.2.0 

func (br *BucketRange) UnmarshalJSON(data []byte) error

type Client added in v0.2.0 

type Client struct {
	// contains filtered or unexported fields
}

Client is a GrowthBook SDK client.

func NewApiClient added in v0.2.0 

func NewApiClient(apiHost string, clientKey string) (*Client, error)

NewApiClient creates simple client with API host and client key

func NewClient added in v0.2.0 

func NewClient(ctx context.Context, opts ...ClientOption) (*Client, error)

NewClient create a new GrowthBook SDK client.

func (*Client) CallFeatureApi added in v0.2.0 

func (c *Client) CallFeatureApi(ctx context.Context, etag string) (*FeatureApiResponse, error)

func (*Client) Close added in v0.2.0 

func (client *Client) Close() error

Close client's background goroutines

func (*Client) DecryptFeatures added in v0.2.0 

func (client *Client) DecryptFeatures(encrypted string) (FeatureMap, error)

func (*Client) EnsureLoaded added in v0.2.0 

func (client *Client) EnsureLoaded(ctx context.Context) error

func (*Client) EvalFeature added in v0.2.0 

func (client *Client) EvalFeature(ctx context.Context, key string) *FeatureResult

EvalFeature evaluates feature based on attributes and features map

func (*Client) Features added in v0.2.0 

func (client *Client) Features() FeatureMap

func (*Client) RunExperiment added in v0.2.0 

func (client *Client) RunExperiment(ctx context.Context, exp *Experiment) *ExperimentResult

func (*Client) SetEncryptedJSONFeatures added in v0.2.0 

func (client *Client) SetEncryptedJSONFeatures(encryptedJSON string) error

SetEncryptedJSONFeatures updates shared features from encrypted JSON. Uses client's decryption key.

func (*Client) SetFeatures added in v0.2.0 

func (client *Client) SetFeatures(features FeatureMap) error

SetFeatures updates shared client features.

func (*Client) SetJSONFeatures added in v0.2.0 

func (client *Client) SetJSONFeatures(featuresJSON string) error

SetJSONFeatures updates shared features from JSON

func (*Client) UpdateFromApiResponse added in v0.2.0 

func (client *Client) UpdateFromApiResponse(resp *FeatureApiResponse) error

UpdateFromApiResponse updates shared data from Growthbook API response

func (*Client) UpdateFromApiResponseJSON added in v0.2.0 

func (client *Client) UpdateFromApiResponseJSON(respJSON string) error

func (*Client) WithAttributeOverrides added in v0.2.0 

func (c *Client) WithAttributeOverrides(attributes Attributes) (*Client, error)

WithAttributeOverrides creates child client instance with updated top-level attributes.

func (*Client) WithAttributes added in v0.2.0 

func (c *Client) WithAttributes(attributes Attributes) (*Client, error)

WithAttributes creates child client instance that uses provided attributes for evaluation.

func (*Client) WithEnabled added in v0.2.0 

func (c *Client) WithEnabled(enabled bool) (*Client, error)

WithEnabled creates child client instance with updated enabled switch.

func (*Client) WithExperimentCallback added in v0.2.0 

func (c *Client) WithExperimentCallback(cb ExperimentCallback) (*Client, error)

WithExperimentCallback creates child client with updated experiment callback function.

func (*Client) WithExtraData added in v0.2.0 

func (c *Client) WithExtraData(extraData any) (*Client, error)

WithExtraData creates child client with extra data that will be sent to a callback.

func (*Client) WithFeatureUsageCallback added in v0.2.0 

func (c *Client) WithFeatureUsageCallback(cb FeatureUsageCallback) (*Client, error)

WithFeatureUsageCallback creates child client with udpated feature usage callback function.

func (*Client) WithForcedVariations added in v0.2.0 

func (c *Client) WithForcedVariations(forcedVariations ForcedVariationsMap) (*Client, error)

WithForcedVariations creates child client with updated forced variations.

func (*Client) WithLogger added in v0.2.0 

func (c *Client) WithLogger(logger *slog.Logger) (*Client, error)

WithLogger creates child client instance that uses provided logger.

func (*Client) WithQaMode added in v0.2.0 

func (c *Client) WithQaMode(qaMode bool) (*Client, error)

WithQaMode creates child client instance with updated qaMode switch.

func (*Client) WithUrl added in v0.2.0 

func (c *Client) WithUrl(rawUrl string) (*Client, error)

WithUrl creates child client with updated current page URL.

type ClientOption added in v0.2.0 

type ClientOption func(*Client) error

func WithApiHost added in v0.2.0 

func WithApiHost(apiHost string) ClientOption

WithApiHost sets the GrowthBook API Host.

func WithAttributes added in v0.2.0 

func WithAttributes(attributes Attributes) ClientOption

WithAttributes sets attributes that used to assign variations.

func WithClientKey added in v0.2.0 

func WithClientKey(clientKey string) ClientOption

WithClientKey sets client key used to fetch features from the GrowthBook API.

func WithDecryptionKey added in v0.2.0 

func WithDecryptionKey(decryptionKey string) ClientOption

WithDecryptionKey sets key used to decrypt encrypted features from the API.

func WithEnabled added in v0.2.0 

func WithEnabled(enabled bool) ClientOption

WithEnabled sets enabled switch to globally disable all experiments. Default true.

func WithEncryptedJsonFeatures added in v0.2.0 

func WithEncryptedJsonFeatures(featuresJson string) ClientOption

WithEncryptedJsonFeatures sets features definitions from encrypted JSON string.

func WithExperimentCallback added in v0.2.0 

func WithExperimentCallback(cb ExperimentCallback) ClientOption

WithExperiementCallbaback sets experiment callback function.

func WithExtraData added in v0.2.0 

func WithExtraData(extraData any) ClientOption

WithExtraData sets extra data that will be to callback calls.

func WithFeatureUsageCallback added in v0.2.0 

func WithFeatureUsageCallback(cb FeatureUsageCallback) ClientOption

WithFeatureUsageCallback sets feature usage callback function.

func WithFeatures added in v0.2.0 

func WithFeatures(features FeatureMap) ClientOption

WithFeatures sets features definitions (usually pulled from an API or cache).

func WithForcedVariations added in v0.2.0 

func WithForcedVariations(forcedVariations ForcedVariationsMap) ClientOption

WithForcedVariations force specific experiments to always assign a specific variation (used for QA)

func WithHttpClient added in v0.2.0 

func WithHttpClient(httpClient *http.Client) ClientOption

WithHttpClient sets http client for GrowthBook API calls.

func WithJsonFeatures added in v0.2.0 

func WithJsonFeatures(featuresJson string) ClientOption

WithJsonFeatures sets features definitions from JSON string.

func WithLogger added in v0.2.0 

func WithLogger(logger *slog.Logger) ClientOption

WithLogger sets logger for GrowthBook client.

func WithPollDataSource added in v0.2.0 

func WithPollDataSource(interval time.Duration) ClientOption

func WithQaMode added in v0.2.0 

func WithQaMode(qaMode bool) ClientOption

WithQaMode if true, random assignment is disabled and only explicitly forced variations are used.

func WithSavedGroups added in v0.2.0 

func WithSavedGroups(savedGroups condition.SavedGroups) ClientOption

WithSavedGroups sets saved groups used to target the same group of users across multiple features and experiments.

func WithSseDataSource added in v0.2.0 

func WithSseDataSource() ClientOption

func WithUrl added in v0.2.0 

func WithUrl(rawUrl string) ClientOption

WithUrl sets url of the current page.

type DataSource added in v0.2.0 

type DataSource interface {
	Start(context.Context) error
	Close() error
}

type Experiment 

type Experiment struct {
	// The globally unique identifier for the experiment
	Key string `json:"key"`
	// The different variations to choose between
	Variations []FeatureValue `json:"variations"`
	// How to weight traffic between variations. Must add to 1.
	Weights []float64 `json:"weights"`
	// Active determines if the experiment is running. If set to false, always return the control (first variation)
	// If nil (field missing in JSON), the experiment is considered active by default.
	Active *bool `json:"active"`
	// What percent of users should be included in the experiment (between 0 and 1, inclusive)
	Coverage *float64 `json:"coverage"`
	// Array of ranges, one per variation
	Ranges []BucketRange `json:"ranges"`
	// Optional targeting condition
	Condition condition.Base `json:"condition"`
	// Each item defines a prerequisite where a condition must evaluate against a parent feature's value (identified by id).
	ParentConditions []ParentCondition `json:"parentConditions"`
	// Adds the experiment to a namespace
	Namespace *Namespace `json:"namespace"`
	// All users included in the experiment will be forced into the specific variation index
	Force *int `json:"force"`
	// What user attribute should be used to assign variations (defaults to id)
	HashAttribute string `json:"hashAttribute"`
	// When using sticky bucketing, can be used as a fallback to assign variations
	FallbackAttribute string `json:"fallbackAttribute"`
	// The hash version to use (default to 1)
	HashVersion int `json:"hashVersion"`
	// Meta info about the variations
	Meta []VariationMeta `json:"meta"`
	// Array of filters to apply
	Filters []Filter `json:"filters"`
	// The hash seed to use
	Seed string `json:"seed"`
	// Human-readable name for the experiment
	Name string `json:"name"`
	// Id of the current experiment phase
	Phase string `json:"phase"`
	// If true, sticky bucketing will be disabled for this experiment.
	// (Note: sticky bucketing is only available if a StickyBucketingService is provided in the Context)
	DisableStickyBucketing bool `json:"disableStickyBucketing"`
	// An sticky bucket version number that can be used to force a re-bucketing of users (default to 0)
	BucketVersion int `json:"bucketVersion"`
	// Any users with a sticky bucket version less than this will be excluded from the experiment
	MinBucketVersion int `json:"minBucketVersion"`
}

Experiment defines a single experiment.

func NewExperiment 

func NewExperiment(key string) *Experiment

NewExperiment creates an experiment with default settings: active, but all other fields empty.

func (*Experiment) IsActive added in v0.2.2 

func (e *Experiment) IsActive() bool

IsActive returns whether the experiment is active. Experiments are considered active by default (when Active field is nil).

type ExperimentCallback 

type ExperimentCallback func(context.Context, *Experiment, *ExperimentResult, any)

ExperimentCallback function that is executed every time a user is included in an Experiment.

type ExperimentResult 

type ExperimentResult struct {
	// Whether or not the user is part of the experiment
	InExperiment bool `json:"inExperiment"`
	// The array index of the assigned variation
	VariationId int `json:"variationId"`
	// The array value of the assigned variation
	Value FeatureValue `json:"value"`
	// If a hash was used to assign a variation
	HashUsed bool `json:"hashUsed"`
	// The user attribute used to assign a variation
	HashAttribute string `json:"hashAttribute"`
	// The value of hash attribute
	HashValue string `json:"hashValue"`
	// The id of the feature (if any) that the experiment came from
	FeatureId string `json:"featureId"`
	// The unique key for the assigned variation
	Key string `json:"key"`
	// The hash value used to assign a variation (float from 0 to 1)
	Bucket *float64 `json:"bucket"`
	// The human-readable name of the assigned variation
	Name string `json:"name"`
	// Used for holdout groups
	Passthrough bool `json:"passthrough"`
	// If sticky bucketing was used to assign a variation
	StickyBucketUsed bool `json:"stickyBucketUsed"`
}

type ExperimentStatus added in v0.1.4 

type ExperimentStatus string
const (
	DraftStatus   ExperimentStatus = "draft"
	RunningStatus ExperimentStatus = "running"
	StoppedStatus ExperimentStatus = "stopped"
)

type Feature 

type Feature struct {
	// DefaultValue is optional default value
	DefaultValue FeatureValue `json:"defaultValue"`
	//Rules determine when and how the [DefaultValue] gets overridden
	Rules []FeatureRule `json:"rules"`
}

Feature has a default value plus rules than can override the default.

type FeatureApiResponse added in v0.2.0 

type FeatureApiResponse struct {
	Status            int                   `json:"status"`
	Features          FeatureMap            `json:"features"`
	DateUpdated       time.Time             `json:"dateUpdated"`
	SavedGroups       condition.SavedGroups `json:"savedGroups"`
	EncryptedFeatures string                `json:"encryptedFeatures"`
	SseSupport        bool
	Etag              string
}

type FeatureMap 

type FeatureMap map[string]*Feature

Map of Feature. Keys are string ids for the features. Values are pointers to Feature structs.

type FeatureResult 

type FeatureResult struct {
	RuleId           string              `json:"ruleId"`
	Value            FeatureValue        `json:"value"`
	Source           FeatureResultSource `json:"source"`
	On               bool                `json:"on"`
	Off              bool                `json:"off"`
	Experiment       *Experiment         `json:"experiment"`
	ExperimentResult *ExperimentResult   `json:"experimentResult"`
}

FeatureResult is the result of evaluating a feature.

func (*FeatureResult) InExperiment added in v0.2.0 

func (res *FeatureResult) InExperiment() bool

type FeatureResultSource 

type FeatureResultSource string

FeatureResultSource is an enumerated type representing the source of a FeatureResult. 

const (
	UnknownFeatureResultSource     FeatureResultSource = "unknownFeature"
	DefaultValueResultSource       FeatureResultSource = "defaultValue"
	ForceResultSource              FeatureResultSource = "force"
	ExperimentResultSource         FeatureResultSource = "experiment"
	OverrideResultSource           FeatureResultSource = "override"
	PrerequisiteResultSource       FeatureResultSource = "prerequisite"
	CyclicPrerequisiteResultSource FeatureResultSource = "cyclicPrerequisite"
)

FeatureResultSource values.

type FeatureRule 

type FeatureRule struct {
	// Optional rule id, reserved for future use
	Id string `json:"id"`
	// Optional targeting condition
	Condition condition.Base `json:"condition"`
	// Each item defines a prerequisite where a condition must evaluate against a parent feature's value (identified by id).
	// If gate is true, then this is a blocking feature-level prerequisite; otherwise it applies to the current rule only.
	ParentConditions []ParentCondition `json:"parentConditions"`
	// What percent of users should be included in the experiment (between 0 and 1, inclusive)
	Coverage *float64 `json:"coverage"`
	// Immediately force a specific value (ignore every other option besides condition and coverage)
	Force FeatureValue `json:"force"`
	// Run an experiment (A/B test) and randomly choose between these variations
	Variations []FeatureValue `json:"variations"`
	// The globally unique tracking key for the experiment (default to the feature key)
	Key string `json:"key"`
	// How to weight traffic between variations. Must add to 1.
	Weights []float64 `json:"weights"`
	// Adds the experiment to a namespace
	Namespace *Namespace `json:"namespace"`
	// What user attribute should be used to assign variations (defaults to id)
	HashAttribute string `json:"hashAttribute"`
	// The hash version to use (default to 1)
	HashVersion int `json:"hashVersion"`
	// A more precise version of coverage
	Range *BucketRange `json:"range"`
	// Ranges for experiment variations
	Ranges []BucketRange `json:"ranges"`
	// Meta info about the experiment variations
	Meta []VariationMeta `json:"meta"`
	// Slice of filters to apply to the rule
	Filters []Filter `json:"filters"`
	// Seed to use for hashing
	Seed string `json:"seed"`
	//Human-readable name for the experiment
	Name string `json:"name"`
	// The phase id of the experiment
	Phase string `json:"phase"`
}

type FeatureUsageCallback added in v0.1.4 

type FeatureUsageCallback func(context.Context, string, *FeatureResult, any)

FeatureUsageCallback funcion is executed every time feature is evaluated

type FeatureValue 

type FeatureValue any

FeatureValue is a wrapper around an arbitrary type representing the value of a feature.

type Filter added in v0.1.4 

type Filter struct {
	Seed        string        `json:"seed"`
	Ranges      []BucketRange `json:"ranges"`
	Attribute   string        `json:"attribute"`
	HashVersion int           `json:"hashVersion"`
}

Filter represents a filter condition for experiment mutual exclusion.

type ForcedVariationsMap 

type ForcedVariationsMap map[string]int

ForcedVariationsMap is a map that forces an Experiment to always assign a specific variation. Useful for QA.

type Namespace 

type Namespace struct {
	Id    string
	Start float64
	End   float64
}

Namespace specifies what part of a namespace an experiment includes. If two experiments are in the same namespace and their ranges don't overlap, they wil be mutually exclusive.

func (*Namespace) UnmarshalJSON added in v0.2.0 

func (namespace *Namespace) UnmarshalJSON(data []byte) error

type ParentCondition added in v0.2.0 

type ParentCondition struct {
	Id        string         `json:"id"`
	Condition condition.Base `json:"condition"`
	Gate      bool           `json:"gate"`
}

type PollDataSource added in v0.2.0 

type PollDataSource struct {
	// contains filtered or unexported fields
}

func (*PollDataSource) Close added in v0.2.0 

func (ds *PollDataSource) Close() error

func (*PollDataSource) Start added in v0.2.0 

func (ds *PollDataSource) Start(ctx context.Context) error

type SseDataSource added in v0.2.0 

type SseDataSource struct {
	// contains filtered or unexported fields
}

func (*SseDataSource) Close added in v0.2.0 

func (ds *SseDataSource) Close() error

func (*SseDataSource) Start added in v0.2.0 

func (ds *SseDataSource) Start(ctx context.Context) error

type VariationMeta added in v0.1.4 

type VariationMeta struct {
	// Key is a unique key for this variation.
	Key string `json:"key"`
	// Name is a human-readable name for this variation.
	Name string `json:"name"`
	// Passthrough used to implement holdout groups
	Passthrough bool `json:"passthrough"`
}

VariationMeta info about an experiment variation.

Source Files

View all Source files

Directories

Path Synopsis
internal
condition
value

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.