Core Concepts

A short tour of the four primitives you'll use every day: flags, contexts, environments, and evaluation reasons.

Flags

A flag is a named, typed value the SDK resolves at runtime. Every flag has:

• A key: the string identifier you pass to evaluate().
• A type: boolean, string, number, or JSON object.
• A default value: returned when targeting rules don't match.
• An enabled switch, the kill switch. When off, every evaluation returns the default.
• An ordered list of targeting rules and an optional percentage rollout.

Evaluation context

The context is a bag of attributes you pass at evaluation time. Targeting rules and rollouts read from it. Common attributes:

• userId: used as the bucketing key for percentage rollouts.
• email, plan, country: common targeting dimensions.
• Anything else you want, custom attributes are first-class.

Environments

Each project has independent environments (typically development, staging, and production), each with their own API keys and flag configurations. Promoting a change from staging to production is one click, no redeploy.

Evaluation reasons

Every result includes a reason so you can explain why a flag returned what it did:

• rule_match: a targeting rule matched the context.
• rollout: the user was bucketed into the rollout group.
• flag_disabled: the kill switch is off; default returned.
• flag_not_found: no flag exists with that key; default returned.
• default: no rule matched and no rollout applied.

Caching & freshness

The SDK keeps a local in-memory cache of evaluations so synchronous get() calls return in under 1ms. The cache is populated by evaluate(), evaluateAll(), and the streaming transport. Flag changes propagate via SSE in seconds; if streaming is disabled, the cache is refreshed on each evaluateAll().