Before we talk about the client-side SDK, we need to understand the problem it helps solve and the service it connects to.

The old way: deploy equals release

For many years, software teams treated two very different events as one. Deploying means copying new code onto servers or into an app. Releasing means letting real users see and use the new behaviour. In the old world, the moment code was deployed, everyone saw it. That made every deployment a nerve-wracking event.

Think of a restaurant that can only change its menu by printing brand-new menus for every table at the same time. If a new dish turns out to be a disaster, the staff must run around collecting all the menus again. Now imagine the menu was a tablet on each table, and the manager could hide or show any dish from the kitchen office. That tablet is the idea behind a feature flag.

What a feature flag is

A feature flag (also called a feature toggle) is a named on/off decision that lives outside your code. Your code asks a simple question: “Is the new checkout enabled for this user?” The answer comes from a configuration you can change at any time, from a dashboard, without touching the code again.

Flags separate deploying from releasing. Code can travel to production quietly, days before anyone sees it. Then the business, not the build pipeline, decides when to turn it on.

What Flagsmith adds

You could write flags by hand with a text file, but that gets messy fast. Who changed it? Which users should see it? How do you roll it out to ten percent of people? Flagsmith is a ready-made platform for all of that. It gives you a dashboard where product managers and engineers manage flags, plus libraries (SDKs) that your applications use to read them.

Beyond simple on/off switches, Flagsmith also supports remote config, which means a flag can carry a value such as a number, a piece of text, or a small block of data. For example, a flag called “support-phone-number” could carry the number itself. Change it in the dashboard and every app shows the new number.

Flagsmith is open source and can be used as a hosted cloud service or run on your own servers. That choice matters to companies in regulated industries, because it lets them keep all flag data inside their own network.

The word “client” confuses many newcomers, so let us pin it down before going deeper.

Client and server in one minute

In almost every modern application there are two worlds. The server is a computer in a data centre that you control. The client is the device in the user’s hands: a web browser, a phone app, a tablet. The client asks, the server answers.

Flagsmith offers two families of SDKs, matching these two worlds. A server-side SDK runs inside your own backend code, in languages such as Python, Java, Go, or Node. A client-side SDK runs on the user’s device, in JavaScript for the browser, React, React Native, Flutter, Android, or iOS, among others.

Why the difference is important

The two worlds have very different trust levels. Your server is private. The user’s device is not: anyone can open browser tools and read what your web page contains, or inspect network traffic from a phone. Because of this, a client-side SDK is designed so that it never needs to be handed secrets or your full rulebook.

Instead of downloading the entire set of rules and calculating the answer itself, a client-side SDK asks the Flagsmith service, “Here is who I am. What flags apply to me?” The service does the thinking and replies with a short list of finished answers. This approach is called remote evaluation.

Flagsmith has a small vocabulary. Learn these words once and the rest of the system becomes easy to follow.

Organisation, project, and environment

An organisation is your company’s account. Inside it you create projects, usually one per product, such as “Mobile App” or “Customer Website”. Inside each project you create environments, which are separate copies of your flag settings, typically named Development, Staging, and Production.

Environments exist so that you can experiment freely. A flag can be on in Development, half-on in Staging, and off in Production, all at the same time. Each environment has its own identity for the SDK, which brings us to keys.

Features, flags, and values

In Flagsmith, a feature is the named thing you want to control. For each environment, a feature has an enabled state (on or off) and optionally a value. The pair is what the SDK reads. People often say “flag” and “feature” interchangeably, and that is fine in daily talk.

Environment keys

Every environment has an environment key, a long random string that tells Flagsmith which environment the SDK is talking about. There are two kinds. The client-side environment key is meant to be placed in apps and is not a secret. The server-side key is private and must never appear in a browser or app bundle.

Identities and traits

An identity is a label for one user, such as a user ID or an email hash. When the SDK says “I am identity 42”, Flagsmith can give that person personalised answers. A trait is a small fact about that identity: their plan, their country, their app version, the date they signed up.

If no identity is given, the SDK is anonymous. It still receives the environment’s default flags, but it cannot receive answers tailored to one person.

Segments

A segment is a saved group defined by rules over traits. “Plan equals premium and country equals India” is a segment. Segments are how you say, “Turn this feature on for this group only”. The rules are evaluated on Flagsmith’s side, never exposed in full to the client.

Overrides and multivariate options

A segment can override the default value of a feature. An individual identity can also be overridden, which is useful when you want one named tester to see something special. A multivariate feature goes further by offering several named values and a percentage split, so that thirty percent of people receive option A, thirty percent option B, and forty percent the control.

How the answer is chosen

When an identity asks for a flag, Flagsmith walks a short ladder. If a personal override exists for that identity, it wins. Otherwise, if the identity belongs to a segment with an override, that segment’s value wins. Otherwise the environment default applies. The first match on the ladder is the answer.

Now let us zoom out and see every piece involved when a client-side SDK reads a flag.

The big picture

The system has two halves. The control side is where people create and change flags: the dashboard and the core API behind it. The delivery side is where apps read flags at high speed: the edge API that SDKs call. Between them sits a data store that holds environments, features, segments, and identities, and a small real-time service that can nudge apps when something changes.

flowchart LR
  USER["User Device"] --> APP["Your App UI"]
  APP --> SDK["Flagsmith Client SDK"]
  SDK  CACHE["Local Cache on Device"]
  SDK -->|"HTTPS with client environment key"| LB["Load Balancer and CDN Edge"]
  LB --> EDGE["Flagsmith Edge API"]
  EDGE --> STORE[("Environment and Identity Store")]
  DASH["Flagsmith Dashboard"] --> CORE["Flagsmith Core API"]
  CORE --> STORE
  CORE --> RT["Real-time Update Service"]
  RT -.->|"change signal"| SDK
  SDK -->|"Batched usage analytics"| EDGE

Meet each component

Why reads and writes are split

A busy product might change its flags a few dozen times a day, but read them millions of times a day. Systems with that lopsided shape are best built with a separate, fast path for reads. This is a classic idea in system design, often described as separating the read path from the write path. Flagsmith’s hosted platform follows it by running a distributed edge layer for SDK traffic, so that a spike in app usage does not slow down the dashboard, and a busy dashboard never slows down your customers.

Self-hosted versus hosted

If you use Flagsmith’s cloud, all the delivery components above are run for you. If you self-host, you run the API, a database, and optionally the real-time component yourself, and you point the SDK to your own address instead of the default. The SDK behaves the same either way; only the web address it contacts changes.

The first few hundred milliseconds of your app’s life are the most delicate. This is where the SDK wakes up, gets its settings, and decides what to show.

Step one: initialisation

Every client-side SDK begins with an initialisation call. You give it the environment key and a few options, such as the address of the Flagsmith service, which identity to use, and what to do if the network is unavailable. Think of this as introducing yourself at the front desk: “Hello, I am the Production website, here is my badge.”

During initialisation the SDK does several small jobs, usually in this order. It stores the settings in memory. It checks the local cache for flags saved earlier. It decides whether it needs to contact the server at all. If it does, it sends a request and waits. Meanwhile it exposes a loading state so your app knows the answers are not final yet.

Step two: the first request

The SDK calls the Flagsmith edge service over a secure connection. The key travels in a request header, which is how the service knows which environment to answer for. There are two shapes of request, and the SDK picks one based on whether an identity is present.

In the second case, the SDK also sends the traits it knows. Flagsmith saves them against the identity, so future visits can use them even if the app does not resend everything.

Step three: building the in-memory map

The response is a compact list. Each entry says: the feature name, whether it is enabled, and its value if it has one. The SDK stores the list as a lookup table in memory. From that moment on, reading a flag inside your app is an instant local lookup, not a network trip. This is the single most important performance idea in the whole design: ask the network once, answer from memory many times.

Step four: telling the app it is ready

Once the map is built, the SDK fires a callback or updates observable state so your user interface can redraw. Frameworks like React expose this as a provider that re-renders components when flags arrive. Mobile SDKs offer listeners. This is the moment a hidden button might appear or a banner might change colour.

The loading problem

Because the first network request takes time, the app must decide what to show during that gap. There are three honest choices. It can wait and show a spinner, which is simple but slow-feeling. It can use default flags that you provided in advance, which is fast but may be wrong for a moment. Or it can use the cached flags from the last visit, which is usually right and also fast. Most production apps combine the second and third choices.

A flag has a short life on the device and a long life in the dashboard. Let us follow one flag from the moment a product manager clicks a button to the moment a customer sees the result.

From dashboard click to user screen

Suppose a product manager enables a feature called “new-checkout” for the Production environment and adds a segment rule for premium customers. The change is saved to the data store through the core API. If you use the real-time service, a small signal is also sent to apps that are listening. Apps then fetch fresh answers and update the screen.

sequenceDiagram
  participant PM as Product Manager
  participant DASH as Dashboard and Core API
  participant STORE as Data Store
  participant EDGE as Edge API
  participant SDK as Client SDK
  participant UI as App Screen
  PM->>DASH: Enable new-checkout for premium segment
  DASH->>STORE: Save change
  DASH-->>SDK: Real-time change signal
  SDK->>EDGE: Request flags for identity with traits
  EDGE->>STORE: Read environment, segments, overrides
  STORE-->>EDGE: Rules and values
  EDGE-->>SDK: Final list of flags for this user
  SDK->>UI: Notify that flags changed
  UI->>UI: Show new checkout to premium user

The stages in plain words

Short-lived and long-lived flags

Not every flag follows that full path. Some flags are meant to live for years. A kill switch is a long-lived flag that lets you turn off an expensive or risky feature instantly during an incident. A permission flag controls access to premium features. A remote config value might hold a support phone number forever. By contrast, a release flag should be short-lived, living only until the rollout finishes.

Personalisation is where client-side flags become powerful, and also where mistakes creep in.

Choosing a good identity

The identity is the string you give to Flagsmith to represent a person. Good identities are stable, meaning the same person gets the same string on every visit, and non-sensitive, meaning they do not reveal private details. An internal user ID or a random account number works well. A raw email address is risky because it is personal data that will travel across the network and be stored.

Stability matters because of percentage rollouts. When Flagsmith decides whether someone falls into the “ten percent” group, it does so by turning the identity into a number in a repeatable way. The same identity always lands in the same bucket, so a person does not see the new feature on Monday, lose it on Tuesday, and see it again on Wednesday.

What about anonymous visitors?

Many sites have visitors who have not logged in. If you give no identity, every anonymous visitor receives the environment defaults, so you cannot run a consistent percentage rollout for them. A common solution is to generate a random anonymous ID on the first visit, store it on the device, and use it as the identity. Then the rollout is stable even before login. When the person logs in, you switch to their real identity, understanding that their bucket may change at that moment.

Traits: facts that unlock targeting

Traits are what make segments work. If you never send the user’s plan, you cannot build a segment for premium users. Typical useful traits are plan or subscription tier, country or region, app version, device type, and sign-up date. Keep them small, clear, and non-sensitive.

Where the rules are evaluated

A key point for beginners: the segment rules are checked by Flagsmith, not by the SDK. The SDK sends traits, and the service returns answers. This means your app never sees the segment definitions. A curious user cannot open the page and read “premium users in India get the beta”. They only see the flags that apply to them.

Changing identity during a session

Users log in, log out, and switch accounts. The SDK provides ways to switch identity and to reset to anonymous. Each switch triggers a new request, because the answers may differ. Plan your interface for this moment: a button might appear or disappear after login, so your screens should handle a refresh smoothly rather than flash or jump.

Networks fail, phones go through tunnels, and servers have bad days. A well-built client-side integration keeps working through all of it.

Three layers of safety

Think of three layers, each catching what the previous one missed. First, the in-memory map answers all flag reads during a session. Second, the persistent cache on the device remembers flags between sessions. Third, your default flags provide a last-resort answer when nothing else is available.

flowchart TD
  START["App needs a flag value"] --> MEM{"In-memory map ready?"}
  MEM -->|"Yes"| ANSWER["Return value instantly"]
  MEM -->|"No"| CACHE{"Cached flags on device?"}
  CACHE -->|"Yes"| USECACHE["Use cached flags and refresh in background"]
  CACHE -->|"No"| NET{"Network reachable?"}
  NET -->|"Yes"| FETCH["Fetch from Flagsmith edge"]
  NET -->|"No"| DEFAULTS["Use default flags from the app"]
  USECACHE --> ANSWER
  FETCH --> ANSWER
  DEFAULTS --> ANSWER

The persistent cache

Most client-side SDKs can store the last flags in the browser’s local storage or in the phone’s storage. On the next start, the SDK loads these flags immediately, so the first screen already reflects the correct features, and then it fetches fresh values in the background. This gives you the best of both worlds: instant start and eventual accuracy.

You can usually control how long cached flags are trusted. A short lifetime favours freshness. A long lifetime favours speed and offline resilience. Some SDKs let you choose to use stale cached flags if the network request fails, which is often the right call for apps used on poor connections.

Default flags: your safety net

Default flags are values you ship inside the app itself. They are used when there is no cache and no network, for example a first launch on an aeroplane. Choose them carefully. A good rule is that a default should be the safest, most conservative behaviour. A brand-new, unfinished feature should default to off. A critical safety feature, such as fraud protection, should default to on.

Stale data: a trade-off, not a bug

Caching means that, for a short moment, a user might see a flag value that has just been changed on the dashboard. For most features this is harmless. For a few, such as turning off a feature during an outage, you want changes to arrive fast. That is the job of polling and real-time updates, which we explore in the next chapter.

A flag that cannot change quickly is only half a flag. Here is how the client learns that something has changed.

Option one: fetch on events

The simplest approach is to fetch flags only at certain moments: when the app starts, when the user logs in, and when the app returns to the foreground after being in the background. Many apps do nothing more, and for ordinary release flags that is perfectly adequate. A user who opens the app tomorrow will see tomorrow’s flags.

Option two: polling

Polling means asking again and again on a timer: “Anything new? Anything new?” You pick an interval, such as every thirty or sixty seconds. It is easy and robust, but it has costs. Every poll is a request that uses battery, mobile data, and server capacity. Multiply a small interval by millions of users and the numbers become large. Polling also has an inherent delay: a change can wait up to a full interval before a device notices.

Option three: real-time with server-sent events

Flagsmith supports a real-time mode for client-side SDKs. The app opens a long-lived, one-way connection to a Flagsmith real-time service. When a flag changes, the service pushes a small notice down that connection. The SDK reacts by refreshing its flags. This technique is often called server-sent events, and it is a push model rather than a pull model.

Which one should you pick?

Let the importance of the flag guide you. A cosmetic experiment can wait. A kill switch that protects your payment system during an outage must be fast. Many teams combine approaches: fetch on start and foreground, use real-time for the small set of operational flags, and avoid constant polling on mobile devices where battery life matters.

Do not let the screen flicker

When a flag changes while someone is using the app, the interface may shift under their fingers. A button that suddenly vanishes mid-tap is a poor experience. Good teams decide per feature whether a change should apply instantly or wait until the next screen or session. Flags that alter layout are often safer to apply at the next natural pause.

The client-side SDK is not one single library. It is a family of libraries that all follow the same pattern, each shaped to fit its platform.

The family

Flagsmith provides client-side SDKs for the main places software runs on the user’s side: plain JavaScript for browsers, React and other web frameworks, React Native for cross-platform mobile, Flutter, native Android, and native iOS. Each one offers the same basic abilities, which are initialising with a key, identifying a user, reading a flag, reading a value, setting traits, and listening for changes. What differs is the style, which feels natural to each platform.

Browser concerns

In a browser, flags usually load after the page starts. This creates a risk called flash of default content, where a user briefly sees the old design and then watches it change. Teams reduce this by hiding the affected area until flags are ready, by using cached flags from the previous visit, or by loading flags earlier in the page’s life.

Another browser concern is content blockers. Some privacy extensions block requests to well-known analytics and flag domains. If your flags fail to load for these users, your defaults must be good enough to keep the site working. Self-hosting the API under your own domain is another way to reduce this problem.

Server-side rendering and hydration

Many modern websites render a first version of the page on the server for speed and search engines, then let the browser take over. This is awkward for flags, because the server must know which flags apply before the page is sent, and the browser must agree with it afterwards. If they disagree, the page can flicker or even break.

The usual solution is for the server to fetch the flags once, embed that state in the page, and let the client SDK start from the same state instead of asking again. This idea is called hydration. It avoids a second network request and keeps the server and browser consistent.

Mobile concerns

On phones, apps are paused, resumed, and killed by the operating system all the time. A good integration refreshes flags when the app returns to the foreground, avoids heavy polling to protect battery, and stores the last good flags on the device. Remember also that mobile users may run old versions of your app for months. Your flags must therefore be safe for old code, which means never changing the meaning of an existing flag in a way that would confuse a version released long ago.

A flag system sits on the critical path of almost every screen, so it must be fast, light, and able to survive huge spikes.

Two kinds of performance

There is device performance, which is about how quickly the user sees the right thing, and service performance, which is about how many users the backend can handle. The client-side SDK influences both.

Device performance

Reading a flag from the in-memory map takes almost no time, so you can check flags freely while drawing your screen. The expensive part is the first network trip, which is why caching, defaults, and early loading matter. Another cost is the payload size. Each environment may have hundreds of features, and sending all of them to every device wastes data. Keep your flag list tidy, remove old flags, and avoid putting large blobs of text into flag values.

Service performance and scale

Imagine a popular app with ten million daily users. If each user opens the app four times a day and each start triggers one flags request, that is forty million requests a day, or around four hundred sixty per second on average. Real traffic is lumpy. During a marketing campaign, the peak may be fifty times the average. The delivery layer must handle those peaks without breaking a sweat.

Flagsmith handles this by making the delivery path simple and read-focused. A request carries a key and an identity, and the answer is mostly a lookup plus some rule checks. The hosted platform uses a distributed edge layer so that requests are served from infrastructure near the user, and it keeps this layer separate from the dashboard so that heavy usage never blocks editing. Self-hosted teams usually put several copies of the API behind a load balancer, add a fast cache in front of the database, and scale each part independently.

Protecting the service from the crowd

There are several well-known defences against a stampede. Caching at the edge lets repeated identical requests be answered without touching the database. Rate limiting stops a misbehaving client from flooding the service. Back-off and jitter mean that when requests fail, clients wait a little longer and a little randomly before trying again, so a million devices do not all retry at the same second. Without jitter, a short outage can turn into a long one, because everyone rushes back at once. This pattern is known as a thundering herd.

The client is not a safe place. Security for client-side flags starts from one honest sentence: everything on the device can be read by the person holding the device.

What is public and what is not

The client-side environment key is public by design. Anyone can find it in your page or app. What protects you is that this key only allows reading the flags meant for clients, and it cannot change or delete anything. The server-side key, in contrast, has broader rights and must stay in your backend.

flowchart LR
  subgraph PUBLIC["Public zone - user device"]
    BROWSER["Browser or Mobile App"]
    CKEY["Client Environment Key"]
  end
  subgraph PRIVATE["Private zone - your backend"]
    SERVER["Your Backend Service"]
    SKEY["Server-side Key"]
    AUTHZ["Real Permission Checks"]
  end
  FLAGSMITH["Flagsmith Service"]
  BROWSER --> CKEY
  CKEY -->|"Read only flags for this identity"| FLAGSMITH
  SERVER --> SKEY
  SKEY -->|"Full environment access"| FLAGSMITH
  BROWSER -->|"Requests with user login token"| SERVER
  SERVER --> AUTHZ

The five main security rules

Why remote evaluation helps security

Because the rules are evaluated by Flagsmith and only finished answers are sent down, the device never learns your targeting logic, such as which segments exist or how rollouts are calculated. Competitors cannot easily read your roadmap from your website. It also means that flags with sensitive targeting, such as “show to this named VIP customer”, do not leak the customer list into every browser.

Governance and accountability

A feature flag can change what thousands of users see in seconds, so changes should be traceable. Flagsmith records who changed what and when, and offers features for approvals on sensitive environments. In a serious production setup, you would require a second person to approve changes to Production flags, just as you would for a code change.

Privacy and data protection

Identities and traits are data about people. If you serve users in regions with strict privacy laws, such as the European Union, treat them as personal data where applicable. Prefer pseudonymous identities, tell users in your privacy notice what you collect, and consider self-hosting or choosing a data region if you need data to stay in a specific location.

If you cannot see what your flags are doing, you are driving at night with the headlights off.

Three questions monitoring must answer

First, is the flag system healthy? Are requests succeeding, how long do they take, and how many fall back to defaults? Second, who is seeing what? How many users received the new feature, and from which segments? Third, what happened after the flip? Did errors, speed, or sales change when the flag changed?

Flag usage analytics

Client-side SDKs can report which flags were evaluated and how often, in small batches, so the dashboard can show which features are actually in use. This is valuable for spotting dead flags, which are flags nobody reads any more and which can be safely removed. Without usage data, teams are afraid to delete anything.

Logging for troubleshooting

SDKs can usually print what they are doing: which request they made, what came back, and which flags changed. Turn this on during development and when investigating a bug report. Keep it off or low in production, since logs on devices can be noisy and may expose identity information in places that other software can read.

Connecting flags to the rest of your monitoring

The best flag practice is to tag your errors, traces, and business metrics with the flag state. If your error tracker shows “crash rate doubled” and also shows that every crash had “new-checkout equals on”, you have found your culprit within minutes. Many teams therefore attach active flags as context to their error reports and analytics events, and Flagsmith offers integrations with common analytics and monitoring tools for this purpose.

Alerts that matter

Set alerts on things you can act on: a sudden jump in failed flag requests, a sharp rise in fallback usage, or an error spike that starts exactly when a flag was changed. Also keep a visible log of flag changes, so that during an incident the first question, “what changed recently?”, is answered in seconds.

Teams that use feature flags well tend to reach for the same handful of patterns again and again.

Keep the flag check close to the boundary

A strong structural habit is to check each flag in one place, near the edge of the feature, and then hand the decision to the rest of the code as a plain choice between two behaviours. Scatter the check across twenty files and the day you want to remove it, you will curse yourself. Wrap the decision in a small, named piece of code so the flag appears once and is easy to delete.

The two-path rule

Every flag creates two versions of your product: one with the feature and one without. Both paths need testing. This is why the number of live flags should stay small. Ten independent flags can in theory create more than a thousand combinations, and no team tests all of them. Keep flags independent where possible and retire them quickly.

Strangler-style migrations

Flags are excellent for replacing old systems piece by piece. You build the new path beside the old one, route a small group of users to the new path, compare results, and grow the group until the old path carries no traffic. At that point the old code is deleted. This approach is often called the strangler pattern, and flags are its steering wheel.

Most flag trouble comes from the same few habits. Learn to recognise them early.

A short list of everyday slips

• Unclear names. A flag called “test2” tells nobody anything. Use names that say what the feature does.
• Wrong environment. Changing Production when you meant to change Staging. Colour-code environments and require approvals for Production.
• Unstable identity. Using a value that changes between visits, which makes users flip in and out of experiments.
• Forgetting the off state. Testing only with the flag on. The off path must keep working, since it is your rollback.
• Ignoring old app versions. Changing a flag in a way that confuses builds already out in the world.

Turning a feature on is one question. Learning whether the feature is actually better is a different and more interesting question.

From switch to experiment

A simple flag has two states. A multivariate flag has several named values, each with a share of the audience. Imagine a flag called “checkout-button-text” with three values: “Buy now”, “Place order”, and “Complete purchase”. Flagsmith can give each value to a different slice of users, for example thirty percent, thirty percent, and forty percent, with the forty percent acting as the control, which is the group that sees the current wording and acts as the yardstick.

The client-side SDK receives only the one value that applies to the current identity. The user sees one button text and never learns that other versions exist. Because the identity decides the bucket in a repeatable way, a person keeps the same variant every time they return, which is exactly what a clean experiment needs.

Measuring the result

Flagsmith decides who sees what, but the measuring usually happens in your analytics tool. The client-side SDK can pass the chosen variant to common analytics platforms, so each event, such as “order completed”, can be tagged with the variant that was active. Later you compare the groups: did the variant with “Place order” lead to more completed purchases than the control?

Good experiments follow a few simple habits. Decide the success measure before you start, so you do not go hunting for a result that looks nice. Let the test run long enough to cover a full weekly cycle, because Tuesday shoppers behave differently from Saturday shoppers. Change one thing at a time. And accept that a few percent difference on a small audience can be pure luck, so wait for enough users before drawing conclusions.

Exposure matters

A common beginner mistake is counting people who were assigned to a variant but never actually saw the changed part of the product. If the button text only appears on the final checkout step, then only people who reached that step were really exposed. Record the exposure at the moment the user sees the difference, not at the moment the app starts. This keeps the comparison honest.

Ending an experiment

When the experiment has a clear winner, give the winning value to everyone by setting it as the default, then remove the other variants and the experiment code. Treat the experiment flag as short-lived work, with the same clean-up discipline as any release flag.

Flags decide “whether”. Remote config decides “how much”, “which text”, and “how long”.

What remote config is good for

Remote config means that a feature carries a value, and the app reads that value at run time. Many things that engineers once hard-coded into an app are better as remote values, because they may need to change quickly and for good reasons. A support phone number changes. A promotional banner message changes. The maximum number of photos a free user may upload changes when the business changes its pricing. A timeout for a slow partner service may need to be longer during a busy week.

Value types and discipline

A remote value is usually a piece of text, a number, or a true-or-false choice. Some teams also store a small structured document inside the text. This works, but be careful: a structured value that is wrong, such as a missing bracket, can crash the code that reads it. Always write the reading code defensively. If the value is missing, empty, or malformed, fall back to a sensible built-in value and continue.

Keep values small and boring

Every value you add travels to every device, every time flags are fetched. A handful of short values costs almost nothing. Dozens of long documents will slow startup, especially on weak networks. Treat remote config as a place for small, clear settings, not as a general-purpose database.

Combine flags and values wisely

A single feature can have both an enabled state and a value. For example, a “free-upload-limit” feature could be enabled or disabled, and when enabled it carries the number of allowed uploads. Your code first checks whether the feature is enabled, and if so, uses the value. If it is disabled, the code uses its built-in standard limit. This two-step habit gives you both a safe off switch and a tunable dial.

Flags make products flexible, and flexibility makes testing more interesting. Here is how to keep quality high.

The two-path promise

Every flag you add means your app can behave in at least two ways. Your tests must prove that both ways work. Teams that test only the “on” path discover during an emergency that the “off” path, the one they planned to use as a rollback, has quietly broken. A rollback that does not work is worse than no rollback, because everyone trusts it.

Test layers

Controlling what the test sees

Tests need to be predictable. If a test depends on a live flag that someone may change at any time, the test will fail randomly, and people will stop trusting the test suite. Use fixed values in automated tests. Reserve the live service for a small number of integration checks that are designed to confirm the connection works.

Testing the failure modes

The most valuable and most often skipped tests simulate trouble: the flag service is slow, returns an error, or is completely unreachable. Does the app start? Does it use the cache or the defaults? Does it hang? These tests prove your safety layers work before a real outage tests them for you.

Testing combinations sensibly

You cannot test every combination of ten flags. Instead, test each flag on its own against the normal baseline, and then test any pairs of flags that touch the same screen or share data. Keep a small list of “risky pairs” that the team agrees to cover.

Where Flagsmith runs affects cost, control, speed, and the legal comfort of your lawyers.

Three ways to run it

What a self-hosted setup involves

If you host Flagsmith yourself, you typically run the API as several identical copies behind a load balancer, so that if one fails, others keep serving. You connect them to a managed relational database and keep regular backups of it. You place a cache in front of the busiest read paths. You add monitoring on request rates, errors, and latency. If you use real-time updates, you also run the real-time component and make sure your load balancer allows long-lived connections.

Cloud platforms such as Amazon Web Services make this easy to assemble from managed parts: containers for the API, a managed database, a load balancer in front, and a content delivery network to place cached answers near users. You can spread copies across several availability zones, which are separate buildings within a region, so a single failure cannot take the system down.

Reaching the service from devices

Whatever you choose, devices must be able to reach the API over the public internet with a valid secure certificate. Put the service on a clear address under your own domain if you can. This looks professional, avoids some content blockers, and lets you move the service later without releasing a new app version, because the address in the app never has to change.

High availability thinking

A flag service should degrade gently. Your client-side layers of cache and defaults already protect the user. On the service side, aim for no single point of failure: several API copies, a database with a standby ready to take over, and a plan for restoring from backup. Practise the plan. A backup you have never restored is another kind of hope.

Release management for the service itself

If you self-host, you will upgrade Flagsmith over time. Treat upgrades like any other important change. Try them in Staging first, read the release notes for changes to settings, and keep the ability to roll back. Interestingly, you can use feature flags to manage the rollout of your own applications while Flagsmith itself is updated carefully by conventional means.

When a flag does not behave, the cause is almost always one of a small number of ordinary things. Work through them in order.

Symptom: the flag always shows its default

This usually means the SDK never received a successful answer. Check these in turn. Is the environment key correct and for the right environment? Is the address of the service correct, especially if you self-host? Is a content blocker, firewall, or missing network permission stopping the request? Did initialisation finish before your code read the flag? A frequent beginner error is reading a flag a split second before the SDK has finished loading it, which returns the default.

Symptom: the flag is on in the dashboard but off for my user

Here, the user is probably not matching your rule. Confirm that the identity is the one you think it is. Confirm that the traits were sent and spelled exactly as the segment expects, since “Premium” and “premium” may not match. Check the order of priority: a personal override on that identity wins over a segment, and a segment wins over the default. Finally, check the environment, since the change may have been made in Staging instead of Production.

Symptom: the flag changed but my app still shows the old value

This is caching and refresh timing. Ask how the app learns about changes: does it only fetch at start, does it poll, or does it use real-time? Look at the cache lifetime. Check whether the app is using stale cached flags because the network request failed. A quick test is to close the app fully and reopen it, or to clear the stored cache on a test device.

Symptom: users see different results from run to run

The identity is unstable. Perhaps it is generated freshly each time, or anonymous users get a new random ID after clearing their storage. Use a durable identity, and remember that private browsing windows and cleared data produce a brand-new anonymous visitor.

Symptom: the page flickers when it loads

The page is drawing before flags arrive and then redrawing. Show a neutral placeholder until the flags are ready, use cached flags, or hydrate the browser from flags fetched on the server.

Useful habits when investigating

• Turn on SDK logging on a test device and read exactly what was requested and received.
• Look at the identity in the dashboard. Flagsmith lets you inspect the traits it has stored and the flags it would return for that identity, which quickly separates “rule problem” from “SDK problem”.
• Reproduce with a fresh identity to rule out leftover cached state.
• Check the audit log to see who changed what recently. A teammate’s change an hour ago is a common culprit.

If you remember nothing else from this guide, remember the habits in this chapter. They separate calm, boring flag usage from exciting incidents.

Setting up

• Use one environment per stage. Development, Staging, and Production each get their own key, so a test change can never touch real customers.
• Use only the client-side key on devices. Store it in configuration rather than scattering it through the code.
• Ship sensible defaults. Choose the safest behaviour for each flag when nothing else is known.
• Turn on the persistent cache. Your app starts faster and survives bad networks.

Naming and ownership

• Name flags for what they do, not for who asked or when. A clear name is documentation that never goes out of date.
• Record an owner and a purpose. Use the description field and tags to mark each flag as release, experiment, ops, or permission.
• Set an expected end date for every short-lived flag, and review old flags regularly.

Rolling out

• Go in small steps. Staff first, then one percent, then ten, then fifty, then everyone.
• Watch real metrics between steps, not just the calendar.
• Agree on the rollback trigger in advance. For example, “if the error rate rises by a fifth, we switch it off.”
• Test both paths. The off path is your safety net, so it must be as healthy as the on path.

Running day to day

• Limit who can change Production. Use roles and approvals.
• Keep an audit trail and display recent flag changes in your incident tools.
• Prefer real-time updates only for operational flags. Let ordinary flags refresh when the app starts or returns to the foreground.
• Send app version and platform as traits so you can target safely.

Cleaning up

• Remove the code, then archive the flag. In that order, so no running version loses its switch unexpectedly.
• Use usage analytics to prove a flag is no longer read before deleting it.
• Make clean-up part of the definition of done for the original feature work.

No design is perfect. A client-side SDK with remote evaluation gives you many strengths and a few costs, and you should choose with open eyes.

Key trade-offs in detail

Consistency considerations

Because every device caches flags and refreshes at its own pace, two users can briefly see different versions of the same feature. This is called eventual consistency, and for most product features it is perfectly acceptable. It becomes a problem only when two parts of your system must agree at exactly the same instant. For example, if your front end shows a new pricing page but your server still calculates old prices, customers see confusing totals. For such cases, make the server the source of truth and have the client display what the server says.

You can think of this in terms of the CAP idea from distributed systems: when the network is unreliable, you must choose between always giving an answer and always giving the freshest answer. Flag clients nearly always choose to keep answering, using cached or default values, because an app that keeps working with a slightly old flag is better than an app that freezes.

Let us walk through a complete, realistic example, so every idea from the earlier chapters appears in one place.

The scenario

A fictional online grocery company, FreshCart, has a website and phone apps used by several million people. The team has rebuilt checkout and wants to release it safely. They use Flagsmith with client-side SDKs on the web and mobile apps, and a server-side SDK in their backend.

The plan

flowchart TD
  A["Create flag new-checkout in Flagsmith"] --> B["Deploy code with flag OFF everywhere"]
  B --> C["Enable for staff segment only"]
  C --> D{"Metrics healthy?"}
  D -->|"No"| R["Switch flag OFF and fix"]
  D -->|"Yes"| E["Roll out to 5 percent of users"]
  E --> F{"Errors and sales healthy?"}
  F -->|"No"| R
  F -->|"Yes"| G["Grow to 25, 50, then 100 percent"]
  G --> H["Keep stable for two weeks"]
  H --> I["Remove old code and archive flag"]
  R --> C

Step by step

What made this work

Every layer did its job. Defaults and caches protected the first screen. Stable identities kept users in a consistent bucket. Remote evaluation kept the rollout rules private. Real-time delivery gave the team a fast emergency stop. Server-side checks kept money logic honest. And a clean-up step stopped the flag from becoming permanent clutter.

A quick reference for every important word used in this guide, so you can look up any term in seconds.

Flag systems come with a lot of vocabulary, and teams often use the words loosely. Agreeing on exact meanings avoids confusion in meetings, in incident calls, and in code reviews. The table below gathers the terms in one place, each explained in a single clear sentence or two.

Short answers to the questions people ask most often when they first meet the client-side SDK.

A client-side SDK is a small, careful messenger between your user’s device and a remote switchboard.

You started with a simple problem: releasing software is risky when deploying and releasing are the same event. Feature flags solve that by moving the decision about who sees what out of the code. Flagsmith packages that idea into a dashboard, an edge API, and a family of SDKs. The client-side SDK is the piece living in browsers and apps, and its design choices all follow from one honest fact: the device cannot be trusted with secrets.