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.goThen 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 withhttp.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)answerstrueorfalse;pb.Flags(visitor)answers every flag as amap[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, callpb.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.
