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

Type	Description	Example
Boolean	On/off toggle	new-checkout → true
String	Text value	checkout-theme → "modern"
Number	Numeric value	max-cart-items → 50
JSON	Structured data	banner-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 default value
3. Evaluates targeting rules against the provided context
4. If no rules match, applies the rollout percentage
5. Returns the resolved value

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

Operator	Description	Example
equals	Exact match	plan equals "pro"
not_equals	Not equal	plan not_equals "free"
contains	String contains	email contains "@company.com"
not_contains	String doesn't contain	email not_contains "@test.com"
gt	Greater than	age gt 18
lt	Less than	age lt 65
in	In list	country in ["US", "CA", "UK"]
not_in	Not in list	country 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.