Experiments
track() and the event protocol
track() and the protocol other SDKs implement: which evaluations are exposures, how units are hashed, and the two edge endpoints.On this page
track()
client.track(eventName: string, ctx?: Context): void
client.track(eventName: string, value: number | null | undefined, ctx?: Context): void
client.track("signup_completed", { key: user.id });
client.track("order_total", 129.5, { key: user.id });eventName: 1–64 letters, digits,_ . : / -, starting with a letter or digit. It must equal the event name of a metric in the catalog; events no metric uses are dropped.value: optional finite number, used by value metrics (for example an order total). Conversion and count metrics ignore it.ctx: the same context you evaluate flags with. Only the unit attribute(s) are read and hashed; nothing else leaves the process.- Synchronous, never throws, never performs I/O itself. An invalid name or value emits an
errorwith codeconfigand the event is dropped.
Units
The unit is the attribute the experiment's rollout buckets by: key by default, or the rule's bucketBy. track() reports the event under key and under the unit attribute of every experiment in the bundle in use (for example accountId), so pass the same identifiers you evaluate with. A browser can report conversions for experiments on server-side flags as long as it passes the same identity.
Delivery
- Queued in memory (5,000 exposures and 5,000 events at most) and sent every 5 seconds (
experiments.flushIntervalMs), sooner when 100 are waiting, and onflush()/close(). In serverless functions,await client.flush()before returning. - Exposures go first, then track events. Exposures are retried after a network error, 429 or 5xx (they are de-duplicated); track events are sent at most once.
experiments: falseturns off both exposures andtrack(). Telemetry sampling (events.sampleRate) never applies to them.
Protocol for SDK authors
Every NanoFlags SDK that supports experiments implements the four parts below exactly; the JavaScript SDK is the reference (exposureOf() in the engine, unitHash() in the SDK).
Experiment metadata in bundles
While an experiment runs and its environment is published, the flag in the bundle carries an experiment object. Evaluation ignores it; it only drives exposure logging. Browser keys receive it only for client-exposed flags.
{
"id": "3f1c2b8e-7d52-4c1a-9a43-1f0e6d5b2c11",
"key": "one-page-checkout",
"ruleId": "r2",
"unit": "key",
"traffic": 100,
"seed": "exp:3f1c2b8e-7d52-4c1a-9a43-1f0e6d5b2c11",
"variants": [{ "key": "control", "value": false }, { "key": "treatment", "value": true }]
}When an evaluation is an exposure
- The flag has
experiment, the evaluation's reason is a rule match and its rule id equalsruleId. - The context has the attribute
unit(defaultkey) as a non-empty string or a number; its string form is the identity. - If
trafficis below 100:bucketOf(seed, identity) < traffic, with the engine's bucketing (MurmurHash3 x86 32-bit ofseed + ":" + identity, modulo 10,000, divided by 100). - The served value deep-equals one of
variants[].value; that variant's key is the variant.
Log each (experiment, unit, variant) once per process; do not log from bulk evaluation (all flags at once) or test sessions. Never sample exposures.
The unit hash
unit = lowercase hex SHA-256 of the UTF-8 string
"nanoflags-unit-v1\n" + project + "\n" + environment + "\n" + attribute + "\n" + identity
project, environment: bundle.project and bundle.environment (keys)
attribute: the unit attribute ("key", "accountId", …)Test vector: project commerce, environment production, attribute key, identity user-1 → 1080ed9b5d7279af40f8645e827ac76c42472fdb4a6b33071f2196d9b11817b9. The edge refuses anything that is not 64 lowercase hex characters.
Endpoints
| Endpoint | Body | Answer |
|---|---|---|
POST /v1/exposures | { "sdk": "go/0.3.0", "exposures": [{ "experiment", "variant", "unit" }] } | 202 { accepted, duplicates, ignored, capped } |
POST /v1/track | { "sdk": "go/0.3.0", "events": [{ "event", "unit", "value"? }] } | 202 { accepted, attributed, pending, ignored, capped } |
- Authentication:
Authorization: Bearerwith a client (nf_pub_) or server (nf_srv_) SDK key. CI and admin keys get 403. - At most 500 items and 128 KB per request (send 100 per request). Unknown fields are dropped; invalid items fail the request with 400 and a message naming the item.
401unknown key ·429rate limited (honourRetry-After) ·503temporarily unavailable. Retry exposures on 429/5xx/network errors; do not retry track events.capped: true: the environment's daily allowance is used up; the batch was dropped.