Skip to content
NanoFlags
Start free

Experiments

track() and the event protocol

Metric events tell an experiment what exposed units did. This page covers the JavaScript SDK's track() and the protocol other SDKs implement: which evaluations are exposures, how units are hashed, and the two edge endpoints.

track()

@nanoflags/sdk
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 error with code config and 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 on flush() / 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: false turns off both exposures and track(). 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.

bundle.flags[key].experiment
{
  "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

  1. The flag has experiment, the evaluation's reason is a rule match and its rule id equals ruleId.
  2. The context has the attribute unit (default key) as a non-empty string or a number; its string form is the identity.
  3. If traffic is below 100: bucketOf(seed, identity) < traffic, with the engine's bucketing (MurmurHash3 x86 32-bit of seed + ":" + identity, modulo 10,000, divided by 100).
  4. 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
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

EndpointBodyAnswer
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: Bearer with 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.
  • 401 unknown key · 429 rate limited (honour Retry-After) · 503 temporarily 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.
See also
Experiments for setup and statistics, and Edge HTTP API for the other SDK endpoints.