SDKs
Eight capture SDKs built from one behavioral spec — the same batching, identity and flag semantics on every platform, with public tokens for clients and secret keys for servers.
AZ-Five ships eight capture SDKs: browser + Node, React Native, Python, Go, JVM, Android, iOS/macOS, and Flutter. They are ports of one written specification, and every port must pass the same golden test vectors — so batching, identity handling, session rotation, and flag semantics are identical everywhere. Learn one SDK and you know all eight; the per-SDK pages only differ in language idiom and platform features.
Two credential types
Every SDK authenticates with one of two credentials. They are not interchangeable:
| Public ingest token | Secret API key | |
|---|---|---|
| Format | azfive_pub_… | azfive_… |
| Used by | Browser, Android, iOS, Flutter, React Native | Python, Go, JVM, Node servers |
| Events endpoint | POST /api/v1/events/ingest | POST /api/v1/events |
| Validation | Origin-validated, fail-closed | events:write scope |
| Safe in shipped client code | Yes | No |
Public tokens are scoped to your site’s origins and reject requests from anywhere else. Native mobile apps send no browser Origin header, so they need a token created with “allow no origin” enabled (“Mobile app token” in Settings → API Keys) — requests without an Origin pass, requests with one still validate against the allowed origins.
A public token on /api/v1/events is a hard 403 — server-side capture always uses a secret key. Both credential types are valid on POST /api/v1/decide, which is how server SDKs evaluate feature flags without extra setup.
Install
| Platform | Package | Install |
|---|---|---|
| Browser + Node | npm @azfive/capture | npm install @azfive/capture (CDN via jsDelivr) |
| React Native | npm @azfive/capture-react-native | npm install @azfive/capture-react-native |
| Python | PyPI azfive-capture | pip install azfive-capture (import azfive_capture) |
| Go | azfive-go | go get github.com/az-five/azfive-go |
| JVM | JitPack azfive-jvm | com.github.az-five:azfive-jvm:v0.1.0 |
| Android | JitPack azfive-android | com.github.az-five:azfive-android:v0.1.0 |
| iOS / macOS | SwiftPM | https://github.com/az-five/azfive-ios (iOS 15+ / macOS 12+) |
| Flutter | pub.dev azfive_capture | flutter pub add azfive_capture |
JVM and Android resolve through JitPack — add maven("https://jitpack.io") to your repositories.
Delivery: batching and backpressure
All eight SDKs queue events in memory and deliver in batches with the same defaults: flush at 10 queued events or every 5 seconds, whichever comes first, with the queue bounded at 1,000 events. On overflow the oldest events drop — recent data wins. A failed batch (network error or non-2xx) is re-queued at the front and retried on the next flush tick. A 429 from the server is backpressure, not an error: the batch re-queues and retries next flush.
The public API never throws for delivery or flag problems — network failures are silent, callbacks are guarded, storage failures fall back to memory. Only constructor/config errors (a missing host on a server SDK) raise.
App-platform SDKs flush when the app backgrounds; server SDKs flush at process exit (atexit / Close() / AutoCloseable) and expose an explicit flush.
Feature flags
Flags are evaluated server-side via POST /api/v1/decide — one round trip returns flags, flag payloads, surveys, and the session-recording config. Client SDKs fetch on init and cache with stale-while-revalidate; server SDKs cache per distinct_id with a 60-second TTL.
Reading a flag with getFlag or isFlagEnabled fires an az.flag_called exposure event — the input to experiments — deduplicated per {session|distinct_id}:{flag}:{value}. getFlagPayload never fires an exposure. See Feature flags for targeting and rollout.
Event names
System events live in the reserved az. namespace:
| Event | Emitted by |
|---|---|
az.page_view / az.page_leave | Web page autocapture |
az.interaction | Web DOM click autocapture |
az.screen_view | Mobile screen tracking |
az.identify / az.alias | Identity calls |
az.set / az.set_once | Person property updates |
az.flag_called | Flag exposure |
Custom event names may be anything except the reserved az. prefix, up to 200 characters. Event properties are capped at 64 KiB serialized; oversized or reserved-name events are rejected server-side, reported in the ingest response as rejected.
Reference
Uniform delivery defaults
| Setting | Default | Behavior |
|---|---|---|
| Batch size | 10 | Queue reaching this length triggers an async flush |
| Flush interval | 5,000 ms | Periodic background flush |
| Max queue size | 1,000 | Drop-oldest on overflow |
| Failure handling | Re-queue at front | Retried on next flush; 429 treated the same |
| Error posture | Never throws | Delivery and flag failures are silent |
Endpoints
| Endpoint | Auth | Purpose |
|---|---|---|
POST /api/v1/events/ingest | Public token | Browser/mobile event ingestion |
POST /api/v1/events | Secret key (events:write) | Server event ingestion |
POST /api/v1/decide | Either | Flags, payloads, surveys, recording config |
Captured events land in Product analytics and are queryable like any dataset.