Before learning the words identity and trait, let us feel the problem they solve. It is the problem of treating everybody the same when they are not.

The all-or-nothing switch

The simplest feature flag is a switch with two positions: on or off. When a developer flips it, every user of the product gets the same answer at the same moment. That is fine for a tiny product or an emergency. But most real launches are not all-or-nothing. A team wants to show a new feature to its own employees first, then to a few hundred volunteers, then to ten percent of customers, then to a whole country, and only at the end to everyone. Each of these steps needs the platform to answer a different question: is this particular person in the group that should see it?

What the platform needs to answer that question

To decide if a person belongs to a group, the platform needs two things. First, a way to recognise the person from one visit to the next, so that the answer stays steady. That is the identity. Second, some facts about that person that the group rules can look at, such as which country they live in or which plan they pay for. Those are the traits.

A short story

Ananya works at a language-learning app. Her team has built a new lesson player. They want it to appear only for learners who joined in the last thirty days, because new learners have no old habits to disturb. They also want it only on app versions that contain the new player’s code. Without identities and traits, they would need two separate releases, one for each audience. With them, one feature is released once, and two simple rules decide who sees it. The rules read two traits: the day each learner joined, and the version of the app on their phone.

An identity is Flagsmith’s record of one user, device, or account, recognised by a unique identifier that your application supplies.

A quick map of Flagsmith

Flagsmith is an open-source platform for feature flags and remote configuration. A feature flag is a switch that turns behaviour on or off without a new release. Remote configuration means storing values, such as numbers or text, that an application reads while it runs. Flagsmith arranges things in a tree: an organisation contains projects, a project contains features and segments, and a project also contains environments, such as Development, Staging, and Production. Each environment has its own keys, its own feature states, and its own identities.

flowchart TB
    ORG["Organisation"] --> PRJ["Project: Language App"]
    PRJ --> FEAT["Features and segment definitions, shared"]
    PRJ --> ENV1["Environment: Development"]
    PRJ --> ENV2["Environment: Production"]
    ENV2 --> ID1["Identity: learner 1001 with its traits"]
    ENV2 --> ID2["Identity: learner 1002 with its traits"]
    ENV2 --> ID3["Identity: learner 1003 with its traits"]
    ENV1 --> ID4["Identity: test learner A with its traits"]
    ENV1 --> ID5["Identity: test learner B with its traits"]
    

The simplest definition

An identity is a named person, device, or account that your application tells Flagsmith about. It is recognised by an identifier, a unique piece of text such as a user number. When the application asks Flagsmith for feature answers and includes an identifier, Flagsmith treats that request as coming from one identity, and can give an answer tailored to it.

Four facts every beginner should know

What an identity unlocks

• Segment matching. A segment is a saved group defined by rules over traits. Only identities with traits can match.
• Stable percentage rollouts. The identifier is the input that decides whether a person falls in the ten percent that sees a feature, and keeps them there.
• Multivariate variations. A person is placed in one variation of an experiment, and stays there.
• Personal overrides. A feature state can be given to exactly one identity, such as a beta customer.
• A debugging view. The dashboard can show a particular identity and every feature state it would receive, which is a precious tool when investigating a report.

A trait is one small fact about an identity, stored as a name and a value, that rules can read to decide who belongs in a group.

The simplest definition

A trait is a pair made of a key and a value. The key is the name of the fact, such as “country” or “plan.” The value is the fact itself, such as “India” or “premium.” An identity can carry many traits at once, just as a person can have a country, a plan, an age group, and a favourite language all at the same time.

The kinds of values a trait can hold

Traits can usually hold text, whole numbers, decimal numbers, and true or false values. Choosing the right kind matters, because comparing “is greater than” works on numbers, while “contains” works on text. We will see in a later chapter how mixing the two kinds is a classic source of confusion.

Traits versus feature values

It is easy to confuse traits with feature values, because both are small pieces of information stored with a name. The difference is direction. A trait describes the user and flows from your application to Flagsmith. A feature value describes the behaviour and flows from Flagsmith to your application. Traits are the questions Flagsmith uses. Feature values are the answers it gives.

Traits are not secrets and not a database

Traits are meant to be small, useful facts for decision making. They are not a place to copy your whole customer database. Each extra trait is another thing to keep correct, another thing to protect, and another thing that every environment must send. A good team keeps its trait list short and writes down why each one exists.

Let us open an identity and look inside, to see everything Flagsmith keeps about one person in one environment.

flowchart LR
    REC["Identity record in one environment"]
    REC --> A["Identifier: the unique name you chose"]
    REC --> B["Traits: key and value pairs"]
    REC --> C["Identity overrides: special feature states for this person"]
    REC --> D["Environment: which place this record belongs to"]
    REC --> E["Created and last seen details"]
    B --> B1["country: IN"]
    B --> B2["plan: premium"]
    B --> B3["app_version: 5.2.1"]
    C --> C1["new_checkout: enabled"]
    

Segments are not stored on the identity

Notice what is not inside the record: the list of segments the person belongs to. Segment membership is not stored. It is worked out every time, by checking the identity’s traits against each segment’s rules. This means that when you change a segment’s rules, or when a trait changes, membership updates by itself, with nothing to migrate. It also means that a segment can only ever be as accurate as the traits behind it.

What a feature answer looks like for an identity

When your application asks Flagsmith for the flags of an identity, the reply lists every feature in the environment, with its enabled position and its value, already worked out for that person. The application does not need to know about segments or overrides. It receives the final result, and uses it to choose behaviour.

The identifier is the single most important choice you make about identities. A good one keeps experiences steady and privacy safe. A poor one causes puzzling behaviour for months.

What makes a good identifier

• Unique. No two people share it.
• Stable. It does not change when the person changes their email, name, or phone.
• Opaque. It reveals nothing about the person. A random number or an internal key is better than an email.
• Available early. Your application knows it at the moment it asks for flags.
• The same in every system. Your website, mobile app, and back-end services should send the same identifier for the same person, so that the person gets the same answers everywhere.

Who or what is the identity?

The identity does not have to be a person. It can be a device, an account, an organisation, or a session. Each choice has consequences.

The anonymous visitor problem

A visitor who has not signed in has no stable identifier. Applications usually create a random one, store it in the browser or on the device, and send it as the identity. That works, but when the visitor signs in, the application starts sending the account identifier, which is a different identity, and so a different set of traits and possibly a different experience. Plan for this moment. Some teams keep using the anonymous identifier even after sign-in for the length of an experiment. Others accept the change and avoid running experiments across the sign-in boundary.

Questions to ask before you lock in the identifier

A short meeting on identifiers saves months of rework. Gather the people who build the website, the mobile apps, the back-end services, the analytics, and customer support, and ask each group the same questions. Does your system know the identifier at the moment it asks for flags? Does it stay the same when the person changes their email address, their name, or their phone? Can two people share it by accident, for example members of one family using one login? Can one person own two of them, for example a work account and a personal account? The answers often reveal that two teams have been using two different numbers for the same human being.

Write the final decision on one page, and keep it next to the trait dictionary. The page should say what the identifier is, where it comes from, who is allowed to create it, and what happens to the identity when a customer closes their account. This small document answers many later arguments before they begin.

A trait is cheap to create and expensive to live with. A little design at the start prevents years of confusion.

Start from the rules, not from the data

The best way to choose traits is to work backwards from the decisions you want to make. List the groups you expect to need: employees, premium customers, new users, regions, app versions. For each group, ask which fact would describe it. The answer is your trait. This keeps the list short and every trait purposeful.

A trait dictionary

Keep one shared document, a trait dictionary, that lists every trait the product sends. For each one, it should say the exact key, the kind of value, the allowed values, who sends it, and which segments use it. It sounds like paperwork, but it prevents the most common failure of all: two teams sending the same fact under two names.

Naming rules

• One style, everywhere. Choose lower-case words joined by underscores, and never mix styles, because “Plan,” “plan,” and “user_plan” are three different keys to a computer.
• Say what it is, not how it is used. “plan” lasts longer than “premium_check.”
• Keep the key stable. Renaming a trait silently breaks every segment that reads it.
• Prefer positive names. “is_staff” is clearer than “not_customer.”
• Avoid personal data in the key or value. A trait called “email” is a risk. A trait called “email_domain_is_company” may be enough for your rule.

Value rules

• Choose one spelling and one case. Decide that countries are upper-case two-letter codes, and keep to it.
• Use real numbers for numbers. Send 12, not the text “twelve,” if a rule will ask whether it is bigger than ten.
• Prefer a few clear values over free text. A trait with five possible values is easy to write rules for. A trait that holds anything is not.
• Turn dates into useful numbers. Instead of storing a date of birth, store “age_band” or “days_since_signup,” which is what the rule actually needs and is less sensitive.
• Keep values small. Traits are not the place for paragraphs of text.

Traits do not appear by magic. Your application must send them. Understanding the routes tells you when a trait is current and when it is stale.

The SDK and the environment key

An SDK, or software development kit, is a small library that you add to your application so it can talk to Flagsmith in its own programming language. When the SDK starts, it is given the environment key, which tells Flagsmith which environment the application belongs to. Every later request carries this key, so the identity and its traits are recorded in the right environment.

Four ways traits reach Flagsmith

sequenceDiagram
    participant U as User
    participant A as Application
    participant SDK as Flagsmith SDK
    participant FS as Flagsmith
    U->>A: Signs in and opens the app
    A->>A: Collect identifier and traits from own data
    A->>SDK: Get flags for identity with traits
    SDK->>FS: Request using environment key, identifier, and traits
    FS->>FS: Create or find the identity in this environment
    FS->>FS: Save or update the traits sent
    FS->>FS: Match traits against segment rules
    FS->>FS: Work out feature states for this identity
    FS-->>SDK: Enabled position and value for each feature
    SDK-->>A: Flags kept in memory
    A-->>U: Shows the right version of the app
    

Stored traits versus transient traits

In the usual way of working, traits sent to Flagsmith are stored on the identity, and are remembered for the next request. This is convenient, because traits sent once, such as the date of sign-up, stay available. But in some situations you do not want Flagsmith to remember anything. Flagsmith supports sending transient information, meaning the identity, or particular traits, are used for working out the answers during that request and then forgotten. This is useful for privacy-sensitive facts, for very large numbers of short-lived visitors, and for facts that are only true right now, such as the current page or the current network speed.

What happens with local evaluation

With local evaluation, a back-end server downloads all the rules and states of an environment, and works out answers itself, from memory. It never has to ask Flagsmith about each user. In that mode, the traits come from you, supplied in every call, and they are used for that call only. This is fast and private, but it means your application must always provide the traits it wants rules to see, since there is no stored copy to fall back on.

Choosing the right moment to send traits

The moment you send traits decides how current they are. Three moments matter most. At application start, the application knows the customer and can send everything. At sign-in, the identity changes from visitor to customer, so traits must be sent again under the new identifier. At a life event, such as an upgrade, a change of country, or a new app version after an update, the relevant trait should be updated immediately and the flags refreshed, so the person sees the change without waiting for the next visit.

Many teams forget the second moment. A visitor who browsed anonymously and then signed in is a new identity to Flagsmith, with no traits at all until the application sends them. Always send the full trait set right after sign-in, before showing any screen that depends on a flag.

Traits by themselves do nothing. They become powerful when segment rules read them. This chapter shows how facts become groups.

What a segment is

A segment is a saved, named group defined by rules. It is created once at the project level, so every environment can use it. A segment does not contain a list of people. It contains rules, and anyone whose traits satisfy those rules is in the group at that moment. Examples are “Premium customers in India” or “New users on recent app versions.”

The building blocks of a rule

A segment is built from rules, and each rule is built from conditions. A condition has three parts: the trait key to look at, an operator that says how to compare, and the value to compare against.

Combining conditions: ALL, ANY, and NONE

A rule can say that all its conditions must be true, that any one of them is enough, or that none of them may be true. A segment can hold several rules, and a person must satisfy every rule to be in the segment. Used together, these let you express most real groups.

flowchart TB
    SEG["Segment: Premium learners on new apps"]
    SEG --> R1["Rule 1, ALL of:"]
    SEG --> R2["Rule 2, ANY of:"]
    SEG --> R3["Rule 3, NONE of:"]
    R1 --> C1["plan equals premium"]
    R1 --> C2["signup_days less than 30"]
    R2 --> C3["country equals IN"]
    R2 --> C4["country equals SG"]
    R3 --> C5["is_staff equals true"]
    

What happens when a trait is missing

Not everyone has every trait. A visitor who has not signed in has no plan. A new identity may not yet have a country. When a condition looks at a trait that the identity does not have, the usual result is that the condition is not satisfied, so the identity does not match a rule that needs it. The one exception is a “not equals” or “none of” style test, which may behave in ways that surprise beginners. Always test the people with no data, because they are often the largest group.

Segments are shared, overrides are not

The definition of a segment is the same in every environment of the project. But what the segment does, meaning which feature states it overrides, is set separately in each environment. So “Premium customers” means the same group in Staging and Production, while the feature it unlocks can be switched on in Staging and still be off in Production.

Reading the matrix with three questions

When you design or review a rollout that uses traits, three questions keep the thinking clear. First, who is this for: which traits describe the people who should receive the feature, and are those traits reliably present on every platform? Second, who must be protected: which people, such as old app versions, test accounts, or regulated regions, must never see the feature, and have you excluded them with explicit conditions? Third, what happens to everyone else: is the default safe, is it tested, and does the application behave sensibly when Flagsmith gives it no personal answer at all?

Teams that write the answers to these three questions into the ticket before building anything find that most arguments about targeting vanish. The answers become the acceptance test for the segment, and the persona matrix is simply those answers turned into a table. Teams that skip them often discover the missing answer in Production, in front of customers, which is the most expensive place to learn anything.

Finally, remember that a rollout is a story told over days and weeks, not a single switch. Each step should have a named owner, a watched measure, and a clear condition for moving on or going back. Traits and segments give you the dials, but people still have to decide when to turn them, and a calm, written plan makes those decisions easier for everyone involved.

When your application asks for flags, Flagsmith performs a short, repeatable routine. Knowing it lets you predict every answer.

The order of authority

For every feature, Flagsmith asks the same questions in the same order. The first layer that has something to say wins, and the later layers are not consulted.

flowchart TB
    START["Request: identifier and traits"] --> LOAD["Find or create the identity, save the traits"]
    LOAD --> F1{"Is there an identity override for this feature?"}
    F1 -- Yes --> OUT1["Use the identity override"]
    F1 -- No --> F2{"Does the identity match any segment that overrides this feature?"}
    F2 -- Yes --> PRI["Pick the matching segment with the highest priority"]
    PRI --> OUT2["Use that segment's state or value"]
    F2 -- No --> F3{"Is the feature multivariate or a percentage split?"}
    F3 -- Yes --> HASH["Hash identifier and feature to choose a variation"]
    HASH --> OUT3["Use the chosen variation"]
    F3 -- No --> OUT4["Use the environment default state"]
    

A worked example

A feature called “new player” has these settings in Production. The default is off. A segment “Employees” turns it on and sits first in the priority order. A segment “New learners” sets it on with a value of “tour” and sits second. Beta customer number 884 has a personal override that turns it off.

• Learner 884 has the personal override, so the player is off, even if they are an employee. The personal layer wins.
• An employee who is also a new learner matches both segments. Employees is higher in priority, so the player is on with the Employees setting.
• A new learner who is not an employee matches only the second segment, so the player is on with the value “tour.”
• Everyone else falls to the default, so the player is off.

Predicting an answer before you open the dashboard

With practice, you can predict any answer by walking down the layers in your head. Ask first whether this person has a personal override. If yes, you are finished. If not, list the segments that override this feature in this environment, test the person’s traits against each one, and keep the ones that match. From those, choose the highest in the priority list. If none match, check for variations and a percentage rule. If still nothing, read the environment default. Doing this by hand a few times builds trust in the system, and makes surprising results easy to explain to colleagues.

Remember also that evaluation is about this feature only. Two features can give the same person opposite answers, because each feature has its own overrides, its own priority list, and its own hash recipe. A person can be in the first ten percent for one feature and the last ten percent for another.

Most trait bugs are not clever. They are small disagreements about spelling, case, or type. Learn the usual suspects once and avoid them forever.

Text that looks like a number

The text “10” and the number 10 look identical on a screen but are different things to a computer. If your application sometimes sends the number and sometimes sends the text, rules that compare “greater than” may behave differently for each. Choose one kind per trait and keep it. Even better, record that choice in the trait dictionary.

The case and spelling trap

To a computer, “Premium,” “premium,” and “PREMIUM” are three different values. A segment written for “premium” will quietly ignore someone whose trait says “Premium.” The same goes for stray spaces: “premium ” with a space at the end is not “premium.” The safe cure is a single normalising step in your own code, which trims spaces and puts values into the agreed case before sending.

True, false, and the words “true” and “false”

A real true or false value and the text “true” are different. Some SDKs and some old code send one, some send the other. A segment condition written for one may not match the other. Pick real true or false values for flags like is_staff, and check what your SDK actually sends.

Versions are not numbers

The version “5.10.0” is newer than “5.9.0,” but as plain text “5.10.0” sorts before “5.9.0,” because the character “1” comes before “9.” Comparing versions as text gives wrong answers. Use the version-aware comparison if your Flagsmith offers one, and send versions in one consistent shape, such as three numbers separated by dots.

A trait is a photograph of a moment. People change, and photographs go out of date. Good teams decide how traits are refreshed, and how they are retired.

The life of a trait

stateDiagram-v2
    [*] --> Proposed: Team needs a new fact
    Proposed --> Documented: Added to the trait dictionary
    Documented --> Sending: Application starts sending it
    Sending --> InUse: A segment or rollout reads it
    InUse --> Sending: Value refreshed when it changes
    InUse --> Deprecated: No rule needs it any more
    Deprecated --> Removed: Stop sending and delete stored values
    Removed --> [*]
    

When to refresh

• Every session start. Simple and safe: send all traits whenever the application begins, and no value stays old for long.
• On the event that changes it. When a customer upgrades or changes country, update that trait at once and refresh the flags.
• On a schedule. For values that drift, such as days since signup, a daily job can recompute them. Or, better, compute them in the application at request time.
• Never for permanent facts. A date of signup does not change, so it need be sent only once, though sending it again does no harm.

Removing traits

Traits can also be removed from an identity. Removing is important when a fact stops being true, or when a person asks you to forget something. Setting an empty value is not the same as removing. If a condition checks whether the trait exists, an empty value still counts as present. Use the removal feature of the SDK or API when you mean “this fact no longer exists.”

Drift between systems

The truth about a customer lives in your own database. The traits in Flagsmith are a copy. Like every copy, it can fall behind. If the plan in your billing system changes to free, and the copy says premium, the person keeps premium features until the copy is updated. Decide which system is the source of truth, and make updates flow one way, from your database to Flagsmith, never the other way.

Choosing an owner for every trait

A trait without an owner decays. Nobody notices when it is wrong, nobody removes it when it is useless, and nobody answers questions about it. Give each trait one named owner, a person or a team, who is responsible for three things: that the value is correct at the source, that it is sent whenever it changes, and that it is removed when the last rule that reads it disappears.

Hold a short review every quarter. Open the dictionary and ask of each trait: is any segment still reading it, is the value still correct, is the data still permitted, and could a less sensitive fact do the same job? Traits that fail the review are marked deprecated, then removed. This steady gardening keeps the set small, and keeps the number of surprises small too.

Handling a trait whose meaning changes

Sometimes a business changes what a word means. The plan called “plus” may be split into “plus monthly” and “plus yearly.” If you quietly change the allowed values, every segment that reads “plus” stops matching the new customers. The safe route has four steps. First, add the new values to the dictionary. Second, update every segment that reads the old value so it accepts both. Third, start sending the new values. Fourth, after the old value has disappeared from live identities, tidy the segments. Never change meaning in place.

Sometimes a rule is too broad. You want to treat exactly one person differently. That is an identity override, and it lives in exactly one environment.

What an identity override is

An identity override is a feature state attached to one specific identity in one specific environment. It beats every segment and the default. It answers needs such as “give this customer the beta early,” “switch the new design off for the complaining executive,” or “let our tester see the feature in Production.”

Why each environment keeps its own identities

Identities, traits, and overrides belong to one environment. Your test user in Staging is not the same as the same-named person in Production. This protects real customers from test data, and lets testers experiment freely. It also means that a trait or override you set in Staging does not follow you to Production. You must set up the same behaviour there on purpose.

A clean habit with overrides

Give every identity override a reason and an end date, written somewhere your team can see, such as the ticket that asked for it. Review them on a schedule. An override created for a launch week and forgotten for two years becomes a mystery that engineers will spend hours solving.

Gradual rollouts and experiments need a fair, steady way to place each person in a group. The identifier makes this possible.

What hashing is

A hash is a recipe that turns any piece of text into a number in a fixed range, always giving the same number for the same text. Flagsmith combines the identity and the feature, turns them into a number between zero and one hundred, and compares it to the percentage you set. If the number is below the percentage, the person is in the group.

flowchart LR
    I["Identifier: learner 1001"] --> H["Combine with feature and compute hash"]
    FEAT["Feature: new player"] --> H
    H --> N["Stable number from 0 to 100, say 37"]
    N --> D{"Is 37 below the rollout percentage?"}
    D -- "Rollout 30 percent" --> OUT1["No: not in the group"]
    D -- "Rollout 50 percent" --> OUT2["Yes: in the group"]
    

Why this is so useful

• Stability. A person at 37 stays at 37. They never flip between experiences from visit to visit.
• Growth without churn. Moving from thirty to fifty percent keeps everyone already in, and adds more. Nobody loses the feature.
• Independence between features. Because the feature is part of the recipe, the group chosen for one feature differs from another, so the same unlucky people do not test everything.
• No storage. Flagsmith does not need to remember who is in which group. It recalculates each time.

Multivariate experiments

A multivariate feature has several variations, each with a weight, such as forty percent for blue, forty for green, and twenty for the control. The hash picks one variation for each identity, and keeps them there. This is the foundation of A/B testing, where two or more versions are compared on equal groups.

Mixing traits and percentages

Segments can combine trait conditions with a percentage split. A rule might say “country equals IN, AND percentage split below twenty.” That is a twenty percent trial inside one country. This is how teams roll out region by region and in small steps at the same time.

Reading experiment results honestly

Stable groups are only the start of a good experiment. The groups must also be large enough to show a real difference, run long enough to cover a full cycle of behaviour, such as a whole week, and be measured by a goal chosen before the experiment began. Stopping a test the moment the numbers look good is a common way to fool yourself. The feature flag platform gives you the fair split, and your analytics system gives you the evidence. Keep the two connected by recording, with every important event, which variation the person saw.

Also keep in mind that traits can hide unfair splits. If a trait such as country is strongly linked to the result, make sure each variation contains a fair mix of countries. The hash is blind to traits, which usually produces balanced groups for large numbers of people, but small groups can be uneven by chance.

A feature is tested in Development, rehearsed in Staging, and shown to real people in Production. Traits must behave the same way in all three, or testing means nothing.

The rehearsal problem

Suppose your segment says “plan equals premium AND country equals IN.” In Production, real customers carry those traits. In Staging, testers often have no traits at all, because nobody set them up. The feature looks broken in Staging, or worse, looks fine because the test user happens to have an override. In Production, the rule behaves differently. The rehearsal did not rehearse the real thing.

Making environments honest

A segment rule is a small program. Like every program, it deserves tests before real people depend on it.

What to test

• The trait builder. Given sample customer data, does it produce the exact keys, types, and spellings in the dictionary?
• The segment rules. Does each persona land in the segments you expect, and only those?
• The edges. What happens to people with a missing trait, an empty value, a very old app version, or a brand new account?
• The priority order. When two segments match, does the winner have the feature state you intended?
• The application behaviour. Does the app really change what it shows for each state?

The persona matrix

The best tool is a small table that lists named personas on one side and the expected outcome on the other. You create each persona as an identity with fixed traits, and then check the result in the dashboard or through the SDK. The table also becomes living documentation.

Levels of testing

Identity traits are powerful, but every power has a price. Seeing both sides helps you decide how much to use.

Key trade-offs

Deciding how much targeting is enough

Every new targeting dimension multiplies the number of experiences your product can have. Three plans, ten countries, and four app versions already make one hundred and twenty possible combinations, and each combination must be tested, supported, and understood. Teams that target heavily find that a bug report becomes a puzzle: which of the hundred and twenty versions did this person see? The cure is restraint. Use the smallest set of traits that supports your real business needs, and prefer broad groups over narrow ones. When the number of segments for one feature grows past a handful, pause and ask whether the feature is trying to do too much.

Traits describe people. Anything that describes people carries a duty of care. This chapter lists the main risks and the habits that keep them small.

Why traits need special care

An identity and its traits can reveal who someone is, where they live, what they pay, and how they behave. Laws such as the European GDPR and the California CCPA treat information like this as personal data. They give people rights to see, correct, and delete it. Even where no law applies, customers expect you to be careful.

The main risks

Habits that reduce risk

• Collect the minimum. Only send a trait if a rule reads it.
• Use opaque identifiers. Random internal numbers, never emails.
• Prefer derived facts. Send “age_band” instead of a birth date, “is_company_email” instead of the email.
• Use transient mode for sensitive data. Let rules see a fact for one request without storing it, where your Flagsmith version supports it.
• Keep secrets on servers. Use the public client-side key in browsers and apps, and keep the server-side key out of any code that ships to users.
• Never use traits as the only gate for money or safety. Verify entitlements on your own server.
• Plan for deletion. When a person asks to be forgotten, remove their identity and traits from every environment and from any systems connected to Flagsmith.
• Control who can edit. Give edit rights for identities and segments only to people who need them, and review the audit log.

flowchart TB
    DATA["Fact about a person"] --> Q1{"Does any rule read it?"}
    Q1 -- No --> DROP["Do not send it"]
    Q1 -- Yes --> Q2{"Is there a less sensitive derived version?"}
    Q2 -- Yes --> DER["Send the derived version"]
    Q2 -- No --> Q3{"Must Flagsmith remember it?"}
    Q3 -- No --> TRANS["Send as transient, or use local evaluation"]
    Q3 -- Yes --> STORE["Store it, document it, and plan its deletion"]
    

When a person says “I cannot see the feature,” you need a calm, repeatable way to find out why. This chapter gives you that method.

The identity page is your best friend

The dashboard can show an individual identity: its identifier, its traits, its overrides, and the feature states it would receive. This is the first stop in any investigation. It answers the question “what does Flagsmith believe about this person right now?” in seconds.

A debugging routine

What to measure

Logging with care

Log the identifier and the resulting flag states when it helps diagnosis, but avoid logging the full trait set if it holds personal facts. Many teams log only a hashed identifier and the names of the segments matched. Connect Flagsmith’s audit log and webhooks, where available, to your alerting, so that an unexpected rule change is noticed quickly.

Working with support teams

Customer support is often the first to hear that a feature is missing for someone. Give support a simple, safe way to look up an identity, with permission to read but not to change traits and overrides. Give them a short page that explains the four usual causes: wrong environment, missing or misspelt trait, a competing override, and a stale cached answer in the application. Most tickets can then be answered in minutes, without waking an engineer.

Teach support to record the identifier, the time of the report, the app version, and the platform. With these four facts, an engineer can open the identity, read the traits, and often find the cause on the first look. Without them, the first hour is spent asking questions.

Alerting on rule changes

Because a single edit to a segment can change the experience of millions, treat such edits with the care you give code changes. Many teams require a second person to approve changes in Production, use the audit log to see who changed what, and send notifications to a shared channel when a segment or override is edited. If a rollout metric moves right after such an edit, the audit log tells you exactly what changed and when, which turns a long hunt into a short one.

A handful of testers is easy. Millions of users, each with traits, is another world. Here is how to keep the system quick and affordable.

Where the cost comes from

• Number of identities. Every stored identity is a record. Millions of short-lived visitors can fill storage with data nobody will ever read again.
• Number and size of traits. More traits mean larger payloads and slower requests.
• Frequency of requests. Asking Flagsmith on every screen change multiplies traffic.
• Segment complexity. Many segments with long rules take more work to evaluate.

Ways to keep it light

flowchart LR
    APP["Application"] --> CACHE{"Fresh flags in memory?"}
    CACHE -- Yes --> USE["Use them immediately"]
    CACHE -- No --> CALL["Ask Flagsmith with identity and traits"]
    CALL --> OK{"Reply received in time?"}
    OK -- Yes --> SAVE["Keep in memory and use"]
    OK -- No --> DEF["Use built-in safe defaults"]
    

Freshness versus speed

Caching makes the app fast but allows stale answers. A short refresh time gives fresher answers but more traffic. For most features a few minutes is fine. For urgent switches, such as a kill switch for a broken feature, use a shorter refresh or a streaming update, if your Flagsmith offers one. Match the speed to the stakes.

Teams have solved these problems many times. Patterns are the solutions that keep working. Anti-patterns are the traps that keep catching people.

Good patterns

Anti-patterns

If you remember only one chapter for your daily work, make it this one. It gathers the habits that matter most.

Best practices

Common mistakes

A simple adoption path for a new team

A team new to identities and traits does not need to do everything at once. A gentle path works well, with each step useful on its own.

Questions to ask in every design review

• Who is the identity for this feature, a person, an account, or a device?
• Which traits does the rule read, and are they already in the dictionary?
• What does the rule do for a visitor with no data?
• What is the safe default if Flagsmith cannot be reached?
• Does any trait here count as personal or sensitive data, and is there a safer version?
• Who removes this segment and these traits when the launch is finished?

These six questions take five minutes and prevent most of the incidents described in this guide. They also teach new engineers how experienced engineers think about targeting, which is a gift that grows over time.

The ideas of identity and traits are not unique to Flagsmith. Large companies have used the same thinking for years. Here are well-known patterns, described in general terms.

Large technology companies

A famous warning: Knight Capital

In 2012, the trading firm Knight Capital lost a very large sum in under an hour after a deployment went wrong. Reports said that old code, controlled by a switch that had been reused for a new purpose, was accidentally activated on one of its servers. The lesson is not about traits directly. It is about control: switches must be named clearly, retired when finished, rolled out the same way everywhere, and watched closely. Old overrides, old traits, and reused names are the same kind of danger in smaller form.

An invented story to tie it together

Mira leads the platform team at a company that sells online cooking classes. Her team wants to launch live cooking chat. They follow these steps.

Short answers to the questions beginners ask most.

We began with a shopkeeper who treats a regular customer differently from a stranger. We end with a system that does the same for millions of people, safely.

An identity is the name by which Flagsmith knows one user, device, or account in one environment. A trait is a small fact about that identity, such as plan, country, or app version. Segments are saved groups defined by rules over traits, and membership is worked out fresh each time. Flagsmith then evaluates in layers: a personal override first, then the highest-priority matching segment, then a multivariate choice by stable hashing, then the environment default. The first layer with something to say wins.

Because traits describe people, they must be designed, documented, kept fresh, tested through personas, and protected. Most failures come from small disagreements in spelling, type, and ownership, which a trait dictionary and a single trait builder prevent. Most risks come from collecting too much, so send the minimum, use opaque identifiers, prefer derived facts, and never let a client-supplied trait be the only gate for money or safety.