Go SDK

azfive-go is the Go server SDK — events, identity, super properties, and feature flags / experiments, stdlib only. It is a port of @azfive/capture under the shared behavioral spec.

Install

go get github.com/az-five/azfive-go

Use a secret API key with the events:write scope — server SDKs post to /api/v1/events, where public tokens are rejected.

Initialize

import azfive "github.com/az-five/azfive-go"

client, err := azfive.New(azfive.Config{
	APIKey: "azfive_…",
	Host:   "https://app.az-five.com",
})
if err != nil {
	panic(err) // config errors only — delivery problems never error
}
defer client.Close() // drains the queue; Go has no atexit, always Close

New returns an error only for configuration problems (missing key or host). Delivery and flag failures are always silent.

Capture events

Pass the user with the WithDistinctID option; without it, events attribute to the client’s own anonymous id:

client.Capture("invoice_paid", map[string]any{"amount": 99},
	azfive.WithDistinctID("user-42"))

// Super properties — stamped on every event
client.Register(map[string]any{"deployment": "eu-1"})
client.RegisterOnce(map[string]any{"first_seen_version": "2.3"})
client.Unregister("deployment")

Identify & person properties

client.Identify("user-42", map[string]any{"plan": "pro"}, nil) // set, setOnce
client.Alias("legacy-77")
client.PeopleSet(map[string]any{"favorite_color": "teal"}, azfive.WithDistinctID("user-42"))
client.PeopleSetOnce(map[string]any{"signup_date": "2026-08-01"}, azfive.WithDistinctID("user-42"))

Identify with a new id emits az.identify (carrying $anonymous_id) and reloads flags; with the already-identified id it emits a property update only. Reset(false) mints a new anonymous id, clears super properties, keeps the device id, and preserves opt-out; Reset(true) also re-mints the device id. Opt-out controls: OptIn() / OptOut() / HasOptedOut().

Feature flags

Flag methods take the distinct_id first; decide responses are cached per id (60 s TTL, bounded LRU):

if variant, ok := client.GetFlag("user-42", "exp-checkout", nil); ok {
	_ = variant // bool for on/off flags, string for variants
}
if client.IsFlagEnabled("user-42", "new-billing", nil) {
	payload := client.GetFlagPayload("user-42", "new-billing", nil) // no exposure event
	_ = payload
}
client.ReloadFlags("user-42") // bust one id's cache

GetFlag and IsFlagEnabled capture an az.flag_called exposure automatically, deduped on distinctID:flag:value. GetFlagPayload never fires an exposure. The third argument sends optional person properties to /v1/decide for property-based targeting; decide failures serve stale values and never surface as errors.

Flush & shutdown

Events queue in memory and flush every 5 seconds or at 10 queued events. Flush() forces delivery now; Close() drains the queue and stops the worker — always defer client.Close().

Reference

Config

Field	Default	Notes
APIKey	required	azfive_… secret key or azfive_pub_… public token
Host	required	AZ-Five deployment base URL
Project	default	Target project slug
BatchSize	10	Queue length that triggers an async flush
FlushInterval	5s	Background flush period
MaxQueueSize	1000	Queue bound; oldest events dropped on overflow
Gzip	false	Content-Encoding: gzip on event POSTs
OptOut	false	Start opted out of capturing
DisableDecide	false	Disable the /v1/decide flag client

API

New · Capture · Identify · Alias · Reset · GetDistinctID · GetSessionID · Register / RegisterOnce / Unregister · PeopleSet / PeopleSetOnce · OptIn / OptOut / HasOptedOut · GetFlag / IsFlagEnabled / GetFlagPayload / ReloadFlags · Flush · Close.

Behavior notes

• Server runtime: identity is in-memory only, there are no sessions (GetSessionID() returns ""), and events are stamped with $device_type: "Server".
• A distinct_id key inside Capture properties overrides the event’s distinct id and is removed from the properties.
• Failed batches — 429 included — re-queue at the front and retry on the next flush tick, bounded keeping the newest events.
• Custom event names: anything except the reserved az. prefix, ≤ 200 characters; properties ≤ 64 KiB serialized.