Before learning how segments work, it helps to feel the problem they solve.

The problem with “on for everyone”

A feature flag is a switch that turns a feature on or off without releasing new code. The simplest switch is on for everyone or off for everyone. That is useful, but it is also blunt. If the feature has a hidden problem, everyone meets that problem at the same moment. If you only wanted to try it with a few people, a single global switch cannot do that.

The wish to choose who

Teams quickly develop a list of wishes. Show the new checkout page to our own employees first. Turn on the beta dashboard for customers who joined the beta programme. Offer the discount banner only in one country. Keep an old feature alive for a customer who has not upgraded. Each wish is the same wish in different clothes: “Let me choose who gets this.”

The answer: describe a group once, use it many times

A segment is a named group of users, defined by rules. Instead of listing people one at a time, you describe what they have in common, such as “their email ends with our company name” or “their plan is premium”. Flagsmith then checks every person against the rules and decides whether they belong. Once the group exists, you can attach it to as many features as you like.

Segments sit on top of a few simple ideas. Let us meet them one by one.

Feature flag

A feature flag is a setting that controls whether a feature is available. The flag lives outside your code, so you can change it from a dashboard. It is like a light switch on the wall: the wiring is already installed, and you only flip the switch.

Feature state

The feature state is the current answer for a feature: on or off, and perhaps a value attached to it. It can be different in different environments, which are separate copies of your setup such as Development, Staging, and Production.

Identity

An identity is one specific user as Flagsmith knows them. Your app gives each person an identifier, such as a user number or an email, and sends it to Flagsmith when it asks what that person should see. Without an identity, Flagsmith can only give the same answer to everybody.

Trait

A trait is a small fact about an identity, such as “country is Canada”, “plan is premium”, or “app version is 4.2”. Your app sends traits to Flagsmith, and Flagsmith can store them. Traits are the raw material that segment rules look at.

Segment

A segment is a named set of rules that looks at an identity and its traits and answers a yes or no question: does this person belong to the group? Because the rules use traits, the same person can enter or leave a segment when their traits change.

A segment is a reusable question about a user, with a name and a clear answer.

A named question

Every segment has a name, such as “Internal staff” or “Premium customers in Europe”. Behind the name is a set of rules. When Flagsmith evaluates a person, it asks, “Do you satisfy these rules?” If yes, the person is in the segment. If no, they are not.

Membership is calculated, not stored

This is a point that surprises many beginners. Flagsmith does not usually keep a list of members for each segment. Instead, it works out membership at the moment it needs to know, using the person’s current traits. If a trait changes tomorrow, the answer changes tomorrow. There is no membership list to update by hand.

A segment alone does nothing

Creating a segment does not change what anyone sees. It only defines a group. To have an effect, the segment must be connected to a feature through an override, which you will meet shortly. A segment is a guest list; the override is the instruction that says what the guests receive.

Rules are built from small parts, and each part has a simple job.

The three parts of a condition

The smallest building block is a condition. A condition has three parts. The first part is the property to look at, such as a trait called “plan”. The second part is the operator, which is the kind of comparison, such as “equals” or “contains”. The third part is the value to compare against, such as “premium”. Together they read like a sentence: plan equals premium.

Rules hold conditions

A rule groups one or more conditions together and says how they combine. A rule may demand that all its conditions are true, that at least one is true, or that none is true. This lets you say things like “country is Canada and plan is premium”, or “country is Canada or country is Mexico”.

Segments hold rules

A segment can hold several rules. The people who satisfy the segment’s rules become its members. Conditions can sit inside rules, and rules can sit inside other rules to a limited depth, which lets you describe fairly complicated groups without writing any code.

flowchart TD
    S["Segment: Premium customers in Canada"] --> R["Rule: ALL of these must be true"]
    R --> C1["Condition: plan equals premium"]
    R --> C2["Condition: country equals Canada"]
    C1 --> P1["Property: trait called plan"]
    C1 --> O1["Operator: equals"]
    C1 --> V1["Value: premium"]
    

Operators decide how a trait is compared with a value. Choosing the right one is half the skill.

Flagsmith offers a set of operators for conditions. The exact list and the exact labels can change between versions, so check the dashboard and documentation for your version. The families below are the ones you can normally expect to find.

Why the type of the value matters

Traits can be text, whole numbers, decimals, or true or false values. A comparison like “greater than” only makes sense for numbers, and “contains” only makes sense for text. If your app sends the number thirty as the text “30”, a numeric rule may behave unexpectedly. Sending traits in a consistent, correct type is one of the simplest habits that prevents surprises.

The “not” family deserves extra care

Operators that mean “is not” or “does not contain” have a tricky side. What should happen when the trait is missing entirely? Is a person with no country trait “not Canada”? Different operators and versions can treat this case differently, so test it rather than guessing. This is one of the most common sources of segments that include more people than intended.

The way conditions combine decides how wide or narrow your segment becomes.

ALL: every condition must be true

With an ALL rule, a person must satisfy every condition inside it. Each added condition makes the group smaller, because each one removes people. “Country is Canada and plan is premium and app version is at least 4” describes a narrow group.

ANY: at least one condition must be true

With an ANY rule, satisfying a single condition is enough. Each added condition makes the group bigger. “Country is Canada or country is Mexico or country is the United States” describes a wide group.

NONE: no condition may be true

With a NONE rule, the person must satisfy none of the conditions. It is a way to exclude. “Not a test account and not an internal user” keeps out a set of people you do not want to count.

Mixing rules

A segment can hold more than one rule, and rules can be nested inside each other to a limited depth. This lets you express: “Must be in North America (ANY of three countries) AND must be premium AND must not be an internal tester (NONE).” Complex groups are possible, but each layer makes the segment harder for the next person to read.

A segment can only be as good as the facts it looks at. Those facts are traits.

Where traits come from

Traits normally arrive from your own application. When your app asks Flagsmith what an identity should see, it can include a set of traits in that request. In many setups, Flagsmith also stores the traits it receives against the identity, so they are available later. Your app is the source of truth; Flagsmith only remembers what it was told.

Traits sent with the request versus stored traits

There are two common ways traits are used. In one, the app sends the traits along with each request, and Flagsmith uses them straight away. In the other, the traits were stored earlier and Flagsmith reads them from its records. Which approach you use depends on your SDK and its settings, and the details differ between remote and local evaluation, which later chapters explain.

Good traits and poor traits

Good traits are stable, meaningful, and cheap to know: plan, country, role, signup date, app version, and whether the user opted in to a beta. Poor traits are noisy or private: a precise location that changes every minute, or a value copied from a private document. Choose traits you can explain to a customer without embarrassment.

An override is the link between a group and a feature. It is where segments finally change behaviour.

What an override does

Every feature has a default state in each environment, such as off with no value. A segment override says, “For people in this segment, give a different answer.” The answer may be a different on or off state, a different remote config value, or a different choice among multivariate options.

One feature, many overrides

A feature can carry several segment overrides at once. Staff might get it on, beta users might get it on with a special value, and everyone else keeps the default. Each override belongs to one feature in one environment, so a segment can be treated differently by different features and different environments.

Same group, different answers

The segment itself is shared, but the override is separate for each feature. “Beta testers” can see the new dashboard but not the new billing page, because you attached the override only to the dashboard feature. This separation keeps segments tidy and reusable.

flowchart LR
    SEG["Segment: Beta testers"] --> O1["Override on Feature A: ON"]
    SEG --> O2["Override on Feature B: value = blue"]
    SEG -. "no override" .-> F3["Feature C keeps its default"]
    

A single person can belong to several segments at once. Flagsmith needs a clear rule for which answer wins.

The problem of two winners

Suppose Maria is a premium customer, lives in Canada, and works at your company. She may belong to three segments. If each segment has an override for the same feature, and the overrides disagree, Flagsmith must pick one. It cannot give her both answers.

Ordered by priority

For each feature, the segment overrides are kept in an order, and the dashboard lets you rearrange that order. When Flagsmith evaluates a person, it checks the overrides in that order and uses the first one whose segment matches. Any later overrides are ignored for that person, even if she belongs to those segments too. In many versions, the topmost override has the highest priority, but confirm how your dashboard displays this.

Why order matters in practice

If “Everyone in Canada” sits above “Internal staff”, then a staff member in Canada gets the Canada answer. If the order is reversed, the staff answer wins. Neither is wrong in itself, but they produce very different experiences, and a surprising order is a common cause of the question, “Why is this person seeing that?”

flowchart TD
    A["Person asks for feature"] --> B{"In first segment override?"}
    B -- Yes --> R1["Use first override"]
    B -- No --> C{"In second segment override?"}
    C -- Yes --> R2["Use second override"]
    C -- No --> D{"In third segment override?"}
    D -- Yes --> R3["Use third override"]
    D -- No --> R4["Use the feature default"]
    

There are two kinds of special treatment, and one of them outranks the other.

Two levels of exception

A segment override gives a special answer to a group. An identity override gives a special answer to one named person. Both change the default, but they work at different sizes: a group and an individual.

The usual order of authority

In Flagsmith’s normal model, an identity override is stronger than a segment override, and a segment override is stronger than the feature default. In other words, the most specific instruction wins. If your own support engineer is forced on for a feature through an identity override, that choice beats any segment she belongs to.

Why this ordering makes sense

Specific beats general in nearly every system people trust. A hand-written note from the manager beats the company handbook. An exception for one customer beats a rule for all customers. Having this clear order lets you debug a surprising result by walking from the top down.

Sometimes you do not know a fact about people. You simply want “some of them”, chosen fairly.

What a percentage split does

A percentage split is a special kind of condition. Instead of looking at a trait like country or plan, it picks a slice of the whole user base, such as ten percent. It is the tool teams use for gradual rollouts: ten percent today, fifty percent next week, everyone after that.

How Flagsmith keeps it fair and steady

Flagsmith does not roll dice every time a person visits. That would flicker the feature on and off for the same person. Instead, it turns the identity, combined with the segment or feature, into a number that stays the same each time. That number decides whether the person falls inside the slice. As far as is publicly described, the same person gets the same answer on every visit, and raising the percentage adds new people without removing those already included.

Why a stable slice matters

Imagine a feature that appears, vanishes, and appears again as a user clicks around. It would feel broken. A stable slice means a person is in the early group or they are not, and moving from ten to twenty percent only adds people at the edge.

flowchart LR
    ID["Identity"] --> H["Turn into a steady number from 0 to 100"]
    H --> Q{"Number below the chosen percentage?"}
    Q -- Yes --> IN["In the slice"]
    Q -- No --> OUT["Outside the slice"]
    

A feature can have more than two outcomes. Segments can steer people toward each one.

What multivariate means

A multivariate feature offers several variations of a value, such as three different button colours, with a chosen share of users for each. It is the basic tool for comparing options side by side.

How segments steer variations

A segment override can pick a particular variation for its members. For example, staff always see variation B so they can review it, while everyone else is split among A, B, and C by the normal percentages. This lets you control who sees what, even inside an experiment.

Keeping experiments clean

If one segment is forced into a variation, those people no longer take part in the fair split, because their answer was fixed on purpose. When you analyse results, exclude them or analyse them separately. Otherwise your numbers will be skewed by people who never had an equal chance.

Segments belong to a project, and that placement shapes how you can reuse them.

The place in the hierarchy

Flagsmith organises work in layers: an organisation contains projects, and a project contains environments and features. Segments are defined at the project level. That means one segment, such as “Internal staff”, can be used by every feature in the project and in every environment of that project.

Define once, apply many times

Because a segment lives at the project level, you change its definition in one place. If the rule for “Internal staff” must now include a new email domain, you update it once, and every feature override using that segment follows. This is one of the strongest reasons to use segments rather than repeating conditions by hand.

The other side of reuse: shared blast radius

Shared definitions also mean shared risk. If someone edits a widely used segment carelessly, many features may change who they target at the same moment. Treat popular segments like shared tools in a workshop: improve them carefully, and tell the others when you do.

flowchart TD
    ORG["Organisation"] --> PRJ["Project"]
    PRJ --> SEG["Segments (defined here)"]
    PRJ --> ENV1["Development environment"]
    PRJ --> ENV2["Production environment"]
    SEG --> ENV1
    SEG --> ENV2
    ENV1 --> FO1["Feature overrides using segments"]
    ENV2 --> FO2["Feature overrides using segments"]
    

Some segments are meant for just one feature, and Flagsmith has a way to say so.

Why one-off segments exist

Sometimes a group is needed only for a single experiment. Creating a project-wide segment for it clutters the shared list with names nobody will ever reuse. Flagsmith supports segments tied to one feature, so that the shared list stays clean. The exact name and behaviour of this option may vary by version, so look for it in your dashboard.

When to choose which

Use a shared, project-level segment when the group has a real, lasting meaning that other features will also care about, such as “Internal staff” or “Enterprise customers”. Use a feature-specific segment when the group is temporary and has no meaning outside one rollout, such as “Ten percent for the March pricing test”.

Not every fact needs to come from your app. Flagsmith can supply a few of its own.

The identity itself as a property

Besides traits, a rule can look at the identity identifier itself. This makes it possible to build a segment like “identifiers that end with a company domain” or, with a modulo condition, “every fifth user”. It requires no extra work from your app, because the identifier is always present.

The environment as a property

Some versions let a rule look at the environment the request comes from. This allows one segment definition to behave differently in different environments. It is a powerful trick and also a source of confusion, so use it only when the benefit is clear and write the reason down.

Anonymous users

People who are not logged in have no identity. A request without an identity cannot be matched to any segment that depends on identity or its traits, so it simply receives the environment defaults. If anonymous visitors matter to you, give them a temporary identifier, such as a random number kept in the browser, and remember that it stops being the same person when the browser forgets it.

Let us follow one request from the moment a person opens the app to the moment a feature appears or does not.

sequenceDiagram
    participant App
    participant FS as Flagsmith
    App->>FS: Identifier plus traits
    FS->>FS: Look for identity override
    FS->>FS: Evaluate segment rules
    FS->>FS: Pick first matching override by priority
    FS->>FS: Fall back to feature default
    FS-->>App: Feature states and values
    

Why you should memorise this order

Nearly every question of the kind “why did this person get that?” is answered by walking down these steps. It turns a mystery into a short checklist.

In remote evaluation, Flagsmith’s servers do the thinking and the app just receives the answer.

How it works

With remote evaluation, the app sends the identifier and traits to Flagsmith’s API. The server runs all the segment checks and returns the final feature states. The app never sees the rules themselves. It only sees the result.

Benefits

The rules stay private because they never leave the server. Changes to segment rules take effect on the next request without any app update. The app code stays small, because it does not need an evaluation engine inside it.

Costs

Each evaluation needs a network trip, which adds a small delay. If Flagsmith cannot be reached, the app needs a fallback plan. And the amount of traffic grows with the number of identity requests.

In local evaluation, the server-side SDK downloads the rules and decides for itself.

How it works

With local evaluation, a server-side SDK downloads an environment document that contains the features, the segments, their rules, and the overrides. It refreshes this document on a regular timer. When your code asks about a user, the SDK evaluates the segment rules right there in your own process, with no network trip per request.

Why this is attractive

Evaluations become very fast, and they keep working if the connection to Flagsmith is briefly lost, using the last downloaded document. It is a good fit for busy back-end services.

What you must give up or watch

Because the SDK holds the rules, it needs a server-side key, which must be kept secret. Changes reach the service only at the next refresh, so there is a short delay. And, importantly, local evaluation must have the traits at hand at the moment of the question, so your code usually passes them in with the request. Details about stored traits differ between modes, so check your SDK documentation.

The kind of app you build changes how segments are used in practice.

Client-side apps

Web pages and mobile apps usually use remote evaluation with a client-side environment key. The key is public, because it sits in code anyone can inspect. The app sends an identifier and traits, and receives the answers. Because the traits come from the user’s device, they are only as trustworthy as the device, a point the security chapters return to.

Server-side apps

Back-end services can use either remote or local evaluation with a server-side key that is kept secret. They usually know more about a user, such as plan and permissions, from trusted internal sources, so they are the best place to compute important traits.

Mixed systems

Many products combine both. The server works out trustworthy traits and either evaluates segments itself or passes the results to the browser. This pattern keeps sensitive logic away from the user’s reach.

Good segments are easy to read, easy to trust, and easy to retire.

Name the meaning, not the mechanics

A name like “Internal staff” tells everyone what the group is for. A name like “Email contains example dot com” tells only how it is built. When the way of finding staff changes, the first name stays true and the second becomes a lie.

Keep each segment about one idea

A segment should answer one question. “Premium customers” is one idea. “Premium customers in Canada who joined before March and use the mobile app” is four ideas glued together, and almost nobody will be able to explain it later.

Describe it

Write a short description saying who owns the segment, what the group means, and why it exists. Six months from now, this single sentence will save an afternoon of detective work.

Prefer stable traits

Segments built on traits that rarely change give calm, predictable behaviour. Segments built on fast-changing traits make people hop in and out, which can confuse both users and analysts.

Most real segments are variations of a few familiar patterns.

Combining recipes

The most useful pattern is a ladder of exposure for a risky feature: staff first, then beta testers, then a small percentage, then everyone. Each rung is a segment override, and each step is only a change of the top of the ladder in the dashboard.

A careful rollout is mostly a story about segments added in a thoughtful order.

flowchart TD
    A["Feature off for everyone"] --> B["On for a few named people (identity overrides)"]
    B --> C["On for internal staff segment"]
    C --> D["On for beta testers segment"]
    D --> E["On for 5 percent slice"]
    E --> F["On for 25 percent slice"]
    F --> G["On for everyone"]
    G --> H["Remove segments and flag from code"]
    

What to watch on every rung

At each step, check the numbers that tell you whether things are fine: error rates, slow responses, support messages, and whatever measure the feature was meant to improve. Wait long enough to see a real pattern before widening the audience. A step that looks quiet for ten minutes may still be hiding a problem that shows up the next morning.

Having a stop button

Before the first rung, decide what you will do if a measure turns bad, and who will do it. The simplest stop is to switch the feature off at the top level. Because the feature is separated from the deployment, this action takes seconds, not hours.

Finishing the story

When the feature reaches everyone and stays stable, remove the segments and the flag from the code. A ladder that stays standing forever becomes clutter and a source of confusion.

Experiments are about learning, and segments decide who takes part in the learning.

Choosing the right audience

An experiment on a new sign-up page should include only people who are signing up. An experiment on a premium feature should include only premium customers. Segments let you narrow the audience to the people who can actually give you an answer, so your numbers are not watered down by people who were never affected.

Keeping the groups comparable

For a fair comparison, the group that sees the change and the group that does not must be alike in every way except the change. A percentage split inside one segment achieves this well, because both halves come from the same pool of people. Comparing one region to another, by contrast, mixes the effect of your change with the differences between regions.

Excluding the noise

Staff, test accounts, and automated checks behave differently from real customers. Use a NONE rule or a separate higher-priority segment to keep them out of the experiment pool, so that your results describe real behaviour.

Many teams use segments to control which paying customers get which features. This works, with some care.

Why teams do it

A segment such as “Enterprise plan” can unlock features for those customers without any new code. Sales can promise a pilot, and an engineer can enable it for one customer through an identity override or a small segment in minutes.

Where the idea can go wrong

Feature flags are designed for controlling rollout, not for being the official record of what a customer paid for. If the billing system says one thing and a segment says another, customers get the wrong features, and nobody can say which system is right. A sensible approach is to treat the billing system as the source of truth, and send the plan as a trait that the segment merely reads.

Server-side enforcement

If a feature really must be restricted to paying customers, the check that matters must happen on the server. A flag shown in the browser decides what is displayed, but a determined person can force the screen open. The server must refuse the underlying action.

Laws, languages, and customs differ from place to place, and segments help software respect that.

Typical uses

A cookie notice may be required in some regions and not others. A payment method may exist only in certain countries. A new service may be allowed in one country but not yet in another. A country trait and a segment per region makes these differences easy to control without separate versions of the app.

The risks of guessing location

Location can come from the user’s profile, the billing address, a language setting, or a guess from the network address. Each has errors. A traveller on holiday, a person using a privacy tool, or an address that was never updated can all be misplaced. For legal matters, choose the most reliable source and enforce the real rule on the server, not only in the flag.

Document the reason

When a segment exists for a legal reason, write that reason in its description. A future engineer who sees an odd region rule should know whether it can be safely changed or whether a lawyer must be consulted first.

Mobile apps can run old versions for years, so version-aware segments are a quiet hero.

The problem of the old app

A web page updates the moment you reload it. A mobile app does not: some people never update. If a new feature needs new code, switching it on for an old app can show a blank screen or crash the app.

The version segment

The app sends its own version as a trait. A segment such as “App version at least 5.0.0” is attached to the feature, so only apps that know how to display it receive it. Version comparisons usually have a special operator that understands numbers like 5.10.0 being newer than 5.9.0, which plain text comparison would get wrong. Check which version operator your Flagsmith offers.

Retiring old versions

A version segment can also support a gentle sunset. A message that says “Please update” can be shown only to apps below a chosen version. Combined with a remote config value, you can even change the message text without a release.

Segments are shared across a project’s environments, but their effects are not.

What is shared and what is separate

The definition of a segment, meaning its rules, is shared across the project. The overrides that attach segments to features are separate in each environment. This means Development can have overrides that Production does not, so you can try a combination safely first.

Promoting changes upward

The usual habit is to build and test overrides in Development, repeat them in Staging, and finally recreate them in Production. Flagsmith offers ways to speed this up, depending on version and plan, but you should always review what you are about to change in Production line by line.

Beware of drift

When environments are configured by hand, they slowly drift apart. Staging says one thing and Production says another, so a test in Staging proves less than you hoped. Periodically compare environments, especially before an important launch.

A segment you have not tested is only a hope.

Test the inside, the outside, and the edge

For every segment, check at least three kinds of people. Check someone who should clearly be inside. Check someone who should clearly be outside. And check the strange ones: a person with a missing trait, with an empty value, with different capital letters, with extra spaces, or with a number sent as text. Edge cases are where segments break.

Use the dashboard to look at one person

The Flagsmith dashboard lets you view an identity, see its traits, and see which segments it belongs to and what its features evaluate to. This is the fastest way to answer “Why did this person get that?” Use it as your first tool when a result is surprising. The exact layout depends on your version.

Test in a safe environment

Create a handful of fake identities in Development with different trait combinations, and keep them as a permanent test set. After every change to a segment, check that set. It is a tiny investment that catches most mistakes.

Automated checks

In your own application tests, replace Flagsmith with an offline stand-in that returns fixed answers, so tests run quickly and do not depend on the network. Separately, run a small number of checks against a real non-production environment to confirm that the rules behave as expected.

Segments are cheap, until there are very many of them, or very complicated ones.

The cost of evaluating

For each identity evaluation, the system must test segment rules. A few simple segments cost almost nothing. Hundreds of deeply nested segments, each with many conditions, cost more, and in local evaluation that cost is paid inside your own service on every request.

Keep rules cheap

Simple comparisons of equality and numbers are quick. Complicated text pattern matching is slower. Prefer simple operators whenever they express your intention, and avoid heavy patterns on busy paths.

The size of the environment document

With local evaluation, every segment and override lands in the document your servers download. A bloated document takes longer to fetch and uses more memory. Remove segments and overrides you no longer use.

Avoid evaluating more than needed

Ask for the features you need, once per request or per session, and reuse the answer, instead of re-asking at every line of code. In remote mode, avoid sending a new identity request for every click when a cached answer is good enough.

A good design assumes that any network service will occasionally fail.

What the app does without an answer

If the app cannot get an answer, it must still behave sensibly. Every flag in your code should have a safe default, usually the conservative choice: the old behaviour, or the feature off. This applies to segment-based behaviour too, because a person who cannot be evaluated simply gets the default.

Caching helps

Many SDKs can remember the last good answer. Local evaluation keeps the last downloaded document. Client-side apps can store the last response on the device. These measures reduce the damage from short outages, though they can serve slightly old answers.

Think about the worst outcome

Consider what happens if segment-based targeting fails and everyone falls back to the default. If the default is “feature off”, the worst result is that fewer people see a new thing. If a default is “premium feature on”, the worst result is that free users briefly see paid features. Choose defaults with this in mind.

flowchart TD
    A["Need a feature answer"] --> B{"Can we reach Flagsmith or a fresh copy?"}
    B -- Yes --> C["Evaluate segments normally"]
    B -- No --> D{"Do we have a cached copy?"}
    D -- Yes --> E["Use the cached answer and log a warning"]
    D -- No --> F["Use the safe default in code and alert the team"]
    

A segment change does not always reach every user in the same instant.

Where delay hides

There are several places where an old answer can linger. A server using local evaluation holds the old document until its next refresh. A browser or phone may have cached the last response. A content delivery layer between you and Flagsmith may hold its own copy for a short time. Each layer is sensible on its own, but together they decide how fast a change spreads.

Trait delay is separate

There is a second kind of lateness. If a user upgrades to premium but the app only sends the trait at the next login, the segment will not recognise them as premium until then. The segment is correct; the trait is old.

Plan for it

Know how long each layer can delay a change, and tell people. If you switch something off in an emergency, remember that a few users may continue to see it for a short time. For truly urgent switches, test how quickly they take effect, before the day you need them.

Segments make decisions from facts. If someone can lie about the facts, they can steer the decision.

Client-side traits can be faked

When a browser or phone app sends its own traits, the user can change them. Someone using the developer tools of the browser can set “plan” to “premium” and ask for the features of that group. If the only protection for a feature is a segment fed by self-reported traits, that protection is weak.

Compute important traits on the server

For anything that matters, have your trusted back end determine the trait, from your own database, and either evaluate on the server or pass only the result to the client. The user then has no way to change the fact that the decision is built on.

Do not hide secrets in segments

A feature gated by a segment is not a secret. Anyone who is allowed in can see it, and anyone who can read the client-side response can see what it contains. Never place passwords, private keys, or confidential data inside a flag value.

The environment key

Client-side keys are public by design and can only read. Server-side keys can read the full environment document in local evaluation, including all segment rules, so they must be stored in a secrets manager and never shipped to a browser or phone.

Segments need facts about people, so they raise questions of privacy that deserve respect.

Collect the minimum

Send only the traits you truly need for targeting. If a decision can be made from a country, do not send a full address. If it can be made from a plan, do not send a payment history.

Prefer identifiers that are not personal

Instead of an email address as an identifier, many teams use an internal user number that means nothing to outsiders. Then if the data ever leaks or is exported, it is far less revealing.

Think about stored traits

Flagsmith may store traits against identities. Treat that stored information as personal data. Understand where it is kept, how long it stays, and how a person’s data can be removed on request. Your organisation’s privacy rules and the laws of the regions you serve apply here, and they should guide your choices.

Avoid sensitive categories

Do not build segments on sensitive personal characteristics unless there is a clear, lawful reason and proper approval. Being able to target a group does not mean you should.

A segment edit can change who sees a feature across the whole product. That deserves clear responsibility.

Roles and permissions

Flagsmith lets you control who can view, create, and edit segments and who can change overrides in each environment. The fine detail of roles and which plans offer them can differ, so check the current documentation. The general principle is to give the widest access in Development and the narrowest in Production.

Approvals for risky changes

For sensitive overrides in Production, a second pair of eyes catches mistakes. Features such as change requests can require approval before a change goes live, and scheduled changes can apply a change at a planned moment. Confirm the availability of these features for your plan.

The audit trail

Flagsmith records who changed what and when. When something odd happens, the audit log is the first place to look, because it tells you whether a segment or override was edited just before the odd behaviour began.

Ownership

Every segment should have an owner who can explain it. Orphaned segments, whose creator left the team long ago, are a hidden risk.

You cannot manage what you cannot see. Make segment effects visible.

Record which variation people saw

When an important decision depends on a segment, log the feature, the result, and, where appropriate, which segment decided it. Without this, support staff and analysts must guess. Keep the logs free of personal details beyond what is needed.

Watch the size of a segment

A segment that suddenly grows or shrinks is a signal. If “Premium customers” doubles overnight, either business is wonderful or a trait is being sent wrongly. Where you can, track how many identities match each important segment over time.

Mark changes on your graphs

Webhooks and the audit log can announce when a segment or override changes. Add those markers to your monitoring graphs, so that when a line bends, you can see whether a change happened at that moment.

Guardrail measures

For each rollout, choose two or three measures that must not get worse, such as error rate, response time, or cancellations, and watch them by group: members of the new segment against the rest.

Everything you can do in the dashboard can usually be done by a program as well.

Why automate

Clicking is fine for a few segments. For dozens of environments, or when teams want segments kept under review like other configuration, automation is better. Flagsmith provides an administration interface for creating and updating segments, rules, and overrides. It needs a more powerful credential than the one used for evaluating features, so protect it carefully.

Segments as reviewed configuration

Some teams keep a description of their segments in a repository, reviewed like any other change, and apply it with a small tool. This gives history, review, and the ability to rebuild an environment from scratch. If you do this, make sure the tool does not delete or change segments that someone created by hand without noticing, since unexpected deletions could change who sees a feature.

Separate evaluation from administration

Remember that asking “what should this person see?” and “change this segment’s rules” use different interfaces and different keys. A server that only evaluates should never hold an administration credential.

These are tried and tested ways of using segments well.

These habits look harmless at first and become painful later.

If you remember only a handful of habits, make them these.

Common mistakes behind these habits

Almost every mistake with segments comes from skipping one of the habits above. Teams forget that overrides have an order, so the wrong answer wins. They trust a browser trait, so a feature leaks. They never retire a segment, so the list fills with names nobody understands. The habits are not complicated; they only need to be done every time.

Here are some stories that show segments at work in ordinary companies.

Let us follow one team through a complete segment-based rollout.

A travel booking company wants to launch a new “flexible dates” search. The feature is risky because it changes the main search page. The team plans a careful rollout.

Step 1: Agree on the traits

The team lists the traits it needs: the user’s country, the app platform, the app version, whether the user is in the beta programme, and whether the account is internal. They write the names, types, and allowed values in a shared document, and the back end begins sending them, computed from the company’s own records.

Step 2: Create the features and segments

They create a feature called “flexible-dates-search” with a description that names the owner and the plan. They create segments called “Internal staff”, “Beta programme members”, and “Mobile app 6.2 or newer”. Each has a clear description.

Step 3: Set the overrides and the order

In Development, they set overrides so staff see the feature. In Staging, they test every combination with the permanent set of fake identities. In Production, the feature is off by default, with overrides for staff first and beta members second. They place the version guard so that apps below 6.2 can never receive the feature, whatever other segments say.

Step 4: Roll out in steps

Day one: staff only. Day three: beta members. Day six: a five percent slice of mobile users on new versions. Day ten: twenty-five percent. At each step the team watches search errors, response time, and the number of completed bookings, comparing members of the feature group with everyone else.

Step 5: A bump

At twenty-five percent, response times for searches rise a little. The team moves the percentage back to five, investigates, finds a slow database query, fixes it, and moves forward again. Because the problem appeared while only a quarter of users were affected, most customers never knew.

Step 6: Finish

When the feature reaches everyone and stays steady for two weeks, the team removes the segment overrides, deletes the feature flag from the code, and archives the flag. They also delete the temporary percentage segment. The permanent segments, such as “Internal staff”, remain for the next project.

flowchart LR
    A["Agree traits"] --> B["Create feature and segments"]
    B --> C["Set overrides and order"]
    C --> D["Staff only"]
    D --> E["Beta members"]
    E --> F["5 percent"]
    F --> G["25 percent"]
    G --> H{"Healthy?"}
    H -- No --> I["Step back and fix"]
    I --> F
    H -- Yes --> J["Everyone"]
    J --> K["Remove flag and temporary segments"]
    

Segments are powerful, and like every power tool, they have costs.

The central trade-off

Every segment buys you flexibility at the price of one more thing to understand. The skill is to add segments that answer real questions and to remove them when the questions are gone. A small number of clear segments beats a large number of clever ones.

When a result surprises you, work through the evaluation steps in order. Most puzzles have simple causes.

A calm routine

First, look at the identity in the dashboard and read its traits. Second, check whether any identity override exists. Third, see which segments it belongs to. Fourth, read the override order for the feature. Fifth, look at the default and the environment. Sixth, look at the audit log for recent edits. Write down what you find, because the same puzzle often returns.

Many teams begin with targeting rules buried in code. Moving them into segments is a calm, step-by-step job.

Find the hidden rules

Search your code for places where behaviour depends on who the user is: checks for staff emails, plan names, countries, or version numbers. List each one with what it does, who owns it, and how often it changes. These are your candidates.

Define the traits first

Make sure the information the rule uses is sent to Flagsmith as a clean, agreed trait. If the code currently inspects an email domain, decide whether to send a simple “is internal” fact computed on the server instead. A clear trait is easier to reason about than a rule over raw data.

Create matching segments and compare

Build the segments so they select the same people as the old code. For a period, run both: let the old code decide, but log when the segment would have disagreed. When the two agree for long enough, switch the code to rely on the segment.

Remove the old rule

Delete the hard-coded check so there is only one source of truth. Leaving both behind is a recipe for confusion when they drift apart.

flowchart LR
    A["Find hidden rules in code"] --> B["Define clean traits"]
    B --> C["Build matching segments"]
    C --> D["Run both and log differences"]
    D --> E["Switch to segments"]
    E --> F["Delete old rules"]
    

Walk through these questions before relying on segments for something important.

How to use the list

Hold a short review before your first important segment goes live, and again whenever your use grows. Ask for real answers, not hopes. Any row where the team hesitates is a place where something will eventually go wrong. Write down the gap, give it an owner, and fix the most dangerous one first.

The best test of a segment is whether you can read it aloud to a colleague and have them understand it at once.

An example in plain words

Suppose a segment is called “Premium customers in North America on new apps”. Read aloud, its rules say: the plan trait equals premium, and the country trait is one of Canada, Mexico, or the United States, and the app version is at least 6.2, and the account is not marked as a test account. That is four ideas in one sentence, and the listener has to hold all of them in their head at once.

The reading test

If you stumble while reading a segment aloud, or need to add the word “except” more than once, the segment is too complicated. Split it. One segment for premium customers, one for the region, and one for the app version can each be read in a breath, and the feature can use them in the order that makes sense.

Questions to ask while reading

Ask yourself who is certainly inside, who is certainly outside, and who sits at the edge. Ask what happens to a person whose trait is missing. Ask whether any condition could be satisfied by accident, such as a text match that also catches an unexpected word. Ask whether the numbers are stored as numbers. Each question takes a few seconds and each has, in someone’s experience, caught a real mistake.

Explaining it to a non-engineer

A product manager or a support agent should be able to understand the segment’s description without knowing how rules are built. If the description needs technical words, rewrite it. “Paying customers in our three North American countries who have updated the app” is a description anyone can read and confirm.

Tools help, but habits keep segments healthy over years. A light process is enough.

Before creating a segment

Look through the existing list first. Often a segment already exists that does what you need, and reusing it avoids duplicates. If you create a new one, write the description immediately: owner, meaning, reason, and, for temporary ones, an expected end date.

Before changing a segment that already exists

Find out which features use it. Tell its owner and the owners of those features. Decide whether the change should apply to everyone who uses it or whether a new segment is more honest. Make the change in Development first, test with the permanent set of fake identities, and then apply it to the live project at a quiet time.

During a rollout

Announce the plan in the team’s chat: which segments, in which order, with which measures to watch. Name the person who can stop the rollout. Record each step so that anyone can see where things stand.

After a rollout

Remove what is finished: the overrides, the temporary segments, and the flag itself in the code. Add a short note to your team’s record describing what was learned. Review the whole list of segments every few months and ask of each, “Who uses this, and do we still need it?”

A quick reference for every important word in this guide.

Short answers to the questions beginners ask most often.

Segments let you say who gets what, without releasing new code.

A segment is a named group defined by rules about an identity and its traits. Membership is calculated when needed, so it follows people as their traits change. A segment does nothing until a feature override connects it to a different answer. When overlapping segments disagree, the first matching override in priority order wins, and an identity override outranks them all.

Segments are defined once per project and reused across features, while their overrides are separate in each environment. Remote evaluation keeps rules on Flagsmith’s servers; local evaluation brings them into your own service for speed. Whichever you choose, give every feature a safe default, treat client-side traits as claims that can be faked, compute important facts on the server, collect the minimum personal data, and keep segments small, named for their meaning, and retired when finished.