How flags work

The building blocks, and how Slydog decides what each user gets.

Organizations and roles

Everything lives in an organization, and organizations are fully separate from each other. Members have one of four roles:

Invite people from Members. An invite link works once, for 7 days, for whoever signs in with the invited email.

Apps and environments

An app holds flags, segments and environments. Use one app per product, or one per codebase.

An environment, such as local, development or production, has its own rules for every flag and its own SDK keys. The same flag can be on in development and off in production. You can copy a flag's rules from one environment to another.

A protected environment asks for confirmation before any change, and the API answers 428 CONFIRMATION_REQUIRED until a request includes "confirm": true. New apps protect production.

Environments can also expire on their own (Pro), which suits one environment per pull request: see API, CI and scripts.

Flags and variations

A flag has a key, such as new-checkout, a type (Boolean, String, Number or JSON) and a list of variations, the values it can serve. One variation is the off variation: what everyone gets while the flag is off. Variations are the same in every environment.

A new flag starts off everywhere. Only flags marked Available to clients can be read with a client key, from browsers and mobile apps; anyone with your app can read their values.

How a flag is evaluated

For one environment and one context, Slydog checks, in order:

  1. Off? Everyone gets the off variation.
  2. Targets: lists of specific keys that get a given variation.
  3. Rules, top to bottom. The first rule whose conditions all match decides.
  4. Default rule: what everyone else gets while the flag is on.

Targets, rules and the default rule each serve either one variation or a percentage rollout.

With the Node.js provider this happens inside your server, from rules it keeps in memory, so reading a flag doesn't wait on the network. With OFREP, Slydog evaluates and answers.

Contexts and context kinds

The evaluation context says who or what you're evaluating for. Its targetingKey is the key that targets and rollouts use. Every other field is an attribute that rules can match.

{ targetingKey: "user-123", plan: "pro", country: "US" }

Each app lists its context kinds, such as user, home or device. A context with no kind is a user. To evaluate for several at once, send a multi-kind context; each target, rule and rollout says which kind it uses:

{
  kind: "multi",
  user: { targetingKey: "user-123", plan: "pro" },
  home: { targetingKey: "home-42" },
}

Rules and conditions

A rule is a list of conditions, all of which must match. A condition takes a context kind, an attribute and an operator:

Any condition can be negated ("is not one of"). The attribute key means the context's key. If the context doesn't have that kind or attribute, the condition doesn't match, negated or not. An attribute that's a list matches when any of its items does.

Segments

A segment is a reusable group, such as "beta testers" or "staff": keys to include, keys to exclude, and rules that match anyone else. Use it in any flag's rules with is in segment, and change who is in it in one place.

Percentage rollouts

A rollout splits a context kind between variations by percentage, say 10% on and 90% off of users. It's sticky: the same key gets the same variation every time, on every server, and changing the percentages moves the fewest people possible. Contexts without a key of the rollout's kind get your code's default.

To raise a rollout on a timetable, such as 5%, 25%, 50% then 100% a day apart, start a ramp when you save the change. A ramp pauses rather than overwrite the rollout if someone changes it by hand.

Making changes

Over a plan's limit

Flags never stop working because of a limit. A month counts as over only when it's more than 2% over the plan's monthly active users. After two months over in a row, the organization gets a grace period, and after that it becomes read-only until it upgrades or usage drops: flags keep evaluating, but nobody can change them. Owners and admins get an email when a grace period starts.