Skip to content
Peekbird

Go SDK

Feature flags and "In your code" experiments on your server, decided the same way the browser decides them, and events sent from it. It's one file in package peekbird, uses only the standard library, and needs Go 1.21 or newer.

Install

Put the file in a folder of its own in your module:

curl --create-dirs -o peekbird/peekbird.go https://peekbird.com/sdk/peekbird.go

Then import it with your module's path, such as example.com/shop/peekbird. To update, download it again. Make one client when your server starts, with a key from Site settings → Server keys:

// import "example.com/yourapp/peekbird": your module's path, then /peekbird.
// Once, when your server starts. The key is in Site settings → Server keys.
pb := peekbird.New(os.Getenv("PEEKBIRD_KEY"))
defer pb.Close()

The client downloads your flags and experiments in the background, then decides locally, checks for changes every 30 seconds and sends events every 5. Until the first download, flags are off and experiments answer no variation:

// Optional: wait for the site's flags and experiments before taking requests.
if !pb.Ready(5 * time.Second) {
	log.Print("Peekbird isn't ready: flags are off and experiments show the original for now")
}

Decide

// In a handler: reads and sets Peekbird's cookies.
visitor := pb.Visitor(w, r)
if pb.Variation("one-page-checkout", visitor) == "one-page" {
	// Show the new version.
}
visitor := pb.Visitor(w, r)
if pb.Flag("new-search", visitor) {
	// The new feature.
}
  • pb.Visitor(w, r) reads Peekbird's cookies and the request's headers, and sets cookies with http.SetCookie: call it before you write the body.
  • pb.Variation(key, visitor) answers the variation's key, or "" when the visitor isn't in the test. It counts them in the test the first time: ask where the variations start to differ.
  • pb.Flag(key, visitor) answers true or false; pb.Flags(visitor) answers every flag as a map[string]bool. Each answer is noted once per visitor, for the Feature flag filter.
switch pb.Variation("pricing", visitor) {
case "yearly-first":
	// ...
case "monthly-first":
	// ...
default:
	// The original: "control", or no variation.
}

Send events

pb.Track(visitor, "purchase", peekbird.Properties{Revenue: 49.9, Currency: "USD", OrderID: "ORDER-123"})
pb.Track(visitor, "signup")
pb.Track(visitor, "watched", peekbird.Properties{Value: 12, Extra: map[string]any{"video": "intro", "muted": true}})
pb.Identify(visitor, peekbird.Identity{ID: user.ID, Email: user.Email, Name: user.Name})

Revenue is an amount of money with its Currency, Value any other amount a goal adds up, and an order with an OrderID counts once. Extra holds other properties: strings, numbers or booleans. A Revenue or Value of 0 isn't sent, which counts the same.

Visitors you describe

visitor := peekbird.VisitorFrom(peekbird.VisitorInput{
	ID:             user.ID, // your own ID for someone signed in: the same answer on every device
	Attributes:     map[string]any{"plan": user.Plan, "lifetimeValue": 250},
	Country:        "US",
	RegionCode:     "TX",
	TimeZone:       "America/Chicago",
	Request:        r, // fields left empty are read from the request
	ResponseWriter: w, // and Peekbird's cookies are set here
})

Attributes are for "Custom attribute" conditions and compare as text. For frameworks that don't use http.ResponseWriter, leave it out and set the cookies yourself:

visitor := peekbird.VisitorFrom(peekbird.VisitorInput{Request: r})
showNew := pb.Variation("checkout", visitor) == "one-page"
for _, cookie := range visitor.Cookies() {
	// Set cookie.String() as a Set-Cookie header on your response.
}

From a request the SDK reads the cookies, User-Agent, Accept-Language, Referer, Sec-GPC, the page's address (with X-Forwarded-Host and X-Forwarded-Proto behind a proxy), and behind Cloudflare CF-IPCountry and CF-Region-Code. What else a server knows, and what it can't, is on Server-side SDKs. The SDK carries its own time zone data, so day and hour conditions work in containers without any.

Middleware

Make the visitor once per request and pass it down in the request's context:

type visitorKey struct{}

// r.Use(withVisitor(pb)) with chi, or wrap your mux with net/http.
func withVisitor(pb *peekbird.Client) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			visitor := pb.Visitor(w, r)
			next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), visitorKey{}, visitor)))
		})
	}
}

With gin:

router.Use(func(c *gin.Context) {
	c.Set("peekbird", pb.Visitor(c.Writer, c.Request))
	c.Next()
})

router.GET("/checkout", func(c *gin.Context) {
	visitor := c.MustGet("peekbird").(*peekbird.Visitor)
	if pb.Variation("checkout", visitor) == "one-page" {
		// ...
	}
})

Echo works the same way, with pb.Visitor(c.Response(), c.Request()).

Consent

Where your site waits for consent (see Consent), the SDK follows the same rule as the snippet. For a visitor who hasn't agreed, it sets no cookies and sends no events, and experiments answer "". Flags are still answered, since deciding one stores and sends nothing. Tell it what your own banner knows with Consent: peekbird.ConsentGiven.

Options

pb := peekbird.NewWithOptions(os.Getenv("PEEKBIRD_KEY"), peekbird.Options{
	RefreshInterval: 30 * time.Second, // between checks for changed flags and experiments; negative: load once
	FlushInterval:   5 * time.Second,  // between sends of waiting events
	Timeout:         5 * time.Second,  // for each request to Peekbird
	OnError:         func(err error) { log.Print(err) },
	HTTPClient:      &http.Client{Transport: myTransport},
})
  • pb.Flush() sends what's waiting and returns when it's done; pb.Close() stops the background work and sends it. In a serverless function, call pb.Flush() before it returns.
  • Nothing in the SDK returns an error or panics into your code. Without OnError, each distinct error is logged once.

Differences from the browser

  • "Matches regex" conditions run on Go's regexp (RE2). Patterns with lookahead, lookbehind or backreferences can't run there, so they never match on Go servers; simple patterns such as @example\.com$ behave the same.
  • Time zone names must be written as in the IANA database (Europe/Berlin). An unknown name counts as UTC.

See what your visitors see.

Start free in a few minutes: one snippet, every feature. Move to a bigger plan when you need more tracked visits.