Skip to main content

Core Concepts

Projects​

A project is a container for your feature flags. Each project has its own set of environments, flags, and team members. Most teams have one project per application.

Environments​

Each project comes with environments (e.g., Development, Staging, Production). Environments are isolated — a flag can be enabled in Development but disabled in Production. Each environment has its own API key that you pass to the SDK.

Feature Flags​

A feature flag is a toggle that controls whether a feature is available. Flags have a key (e.g., new-checkout), a type, and a configuration per environment.

Flag Types​

TypeDescriptionExample
BooleanOn/off togglenew-checkout → true
StringText valuecheckout-theme → "modern"
NumberNumeric valuemax-cart-items → 50
JSONStructured databanner-config → {"text": "Sale!", "color": "red"}

Flag Evaluation​

When you call getBooleanFlag("my-flag", false, context), the SDK:

  1. Looks up the flag configuration (fetched from the API)
  2. If the flag is disabled, returns the type's off value (false, "", 0 or {}) — the default value is only used while the flag is enabled
  3. Evaluates targeting rules against the provided context
  4. If no rules match, applies the rollout percentage (0% means nobody gets the default value)
  5. Returns the resolved value

New flags start at 0% rollout. Enabling a flag that has no rollout and no targeting rules configured sets it to 100% automatically, so flipping a fresh flag on means on for everyone. If you set a rollout percentage or add rules first, enabling leaves them untouched.

Targeting Rules​

Rules let you deliver different flag values to different users. A rule consists of:

  • Attribute — A field from the user context (e.g., plan, country)
  • Operator — How to compare (e.g., equals, contains, in)
  • Value — The expected value

Operators​

OperatorDescriptionExample
equalsExact matchplan equals "pro"
not_equalsNot equalplan not_equals "free"
containsString containsemail contains "@company.com"
not_containsString doesn't containemail not_contains "@test.com"
gtGreater thanage gt 18
ltLess thanage lt 65
inIn listcountry in ["US", "CA", "UK"]
not_inNot in listcountry not_in ["CN", "RU"]

Example​

To enable a flag only for Pro users in the US:

Rule 1: plan equals "pro"
Rule 2: country equals "US"

Both rules must match (AND logic).

User Segments​

Segments are reusable groups of targeting rules. Instead of repeating the same rules across multiple flags, define a segment like "Premium Users" and reference it.

A segment contains one or more rules with the same operators as targeting rules. Segments are available on Pro plans and above.

Percentage Rollouts​

Gradually roll a feature out to a percentage of users. The rollout is deterministic — the same user always gets the same result for a given flag. This is based on a hash of the user_id and the flag key.

Example: Set rollout to 25% → the same 25% of users always see the feature.

tip

Always include userId (or user_id) in your evaluation context when using percentage rollouts. Without it, the SDK can't consistently assign users to the rollout.

Scheduled Releases​

Schedule a flag to change at a specific time. You can schedule:

  • Enable or disable a flag
  • Update the rollout percentage
  • Change the flag value

Schedules are evaluated by a background job that runs every 10 seconds.

Experiments​

Run A/B tests by creating an experiment linked to a flag. Define variants with traffic allocation, start the experiment, and track events to measure which variant performs better.

Audit Logs​

Every flag change is recorded in the audit log — who changed what, when, and in which environment. Retention depends on your plan (7 days on Free, 90 days on Pro, unlimited on Team).

Webhooks​

Get notified when flags change. Configure a webhook URL and select which events to listen for:

  • FLAG_CREATED, FLAG_UPDATED, FLAG_DELETED
  • FLAG_TOGGLED, FLAG_RULES_UPDATED
  • SCHEDULE_EXECUTED

Webhooks include a signature for verification and support automatic retries on failure.