From 6f28d8eb7b65c105a2123f81a49deae8f543a6d5 Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Fri, 27 Jun 2025 13:32:59 -0300 Subject: [PATCH 01/12] docs: add flagsmith core concepts section and data model page --- docs/docs/flagsmith-concepts/_category_.json | 5 ++ docs/docs/flagsmith-concepts/data-model.md | 52 ++++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 docs/docs/flagsmith-concepts/_category_.json create mode 100644 docs/docs/flagsmith-concepts/data-model.md diff --git a/docs/docs/flagsmith-concepts/_category_.json b/docs/docs/flagsmith-concepts/_category_.json new file mode 100644 index 000000000000..86c9fbb89746 --- /dev/null +++ b/docs/docs/flagsmith-concepts/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Flagsmith Concepts", + "position": 4, + "collapsed": true +} diff --git a/docs/docs/flagsmith-concepts/data-model.md b/docs/docs/flagsmith-concepts/data-model.md new file mode 100644 index 000000000000..1c20db83b5a4 --- /dev/null +++ b/docs/docs/flagsmith-concepts/data-model.md @@ -0,0 +1,52 @@ +--- +title: Data Model +sidebar_label: Data Model +sidebar_position: 10 +--- + +Flagsmith uses a flexible data model to help you manage feature flags and remote configurations across multiple projects, environments, and user groups. + +Here's a high-level overview of the Flagsmith data model. Fear not - it's not as complex as it looks! + +![Flagsmith Data Model](/img/flagsmith-model.svg) + +OK let's break this down. + +### Organizations +Organizations allow you and other team members to manage projects and their features. A user can be a member of multiple organizations. + +### Projects +Projects contain one or more Environments that share a single set of Features. Organisations can have any number of Projects. + +### Environments +Environments are a way to separate the configuration of your features. For example, a feature might be enabled in your project's Development and Staging environments but turned off in your Production environment. A project can have any number of environments. + +### Features +Features are shared across all Environments within a Project, but their values/states can be modified per Environment. Features can be toggled on/off or assigned values (e.g., string, integer, boolean, or multivariate values). + +### Identities +Identities are a particular user registration for one of your Project's Environments. Registering identities within the client application allows you to manage features for individual users. Identity features can be overridden from your environment defaults. For example, joe@yourwebsite.com would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment. + +For more info see [Identities](/basic-features/managing-identities). + +### Traits +You can store any number of Traits against an Identity. Traits are key:value pairs that can store any type of data. Some examples of traits that you might store against an Identity might be: +- The number of times the user has logged in. +- If they have accepted the application terms and conditions. +- Their preferred application theme. +- If they have performed certain actions within your application. + +For more info see [Traits](/basic-features/managing-identities.md#identity-traits). + +### Segments +Segments define a group of users by traits such as login count, device, location or any number of custom defined traits. Similar to individual users, you can override environment defaults for features for a segment. For example, you might show certain features for a "power user" segment. + +For more info see [Segments](/basic-features/segments.md). + +## Relationships Summary + +- **Organizations** contain **Projects** +- **Projects** contain **Environments** and **Features** +- **Environments** have their own configuration for each **Feature** +- **Identities** belong to an **Environment** and can be related to **Traits** +- **Segments** group **Identities** by rules on **Traits** From a31cf2e697cf7136d7ed627e940b2067df9892eb Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Fri, 4 Jul 2025 09:28:02 -0300 Subject: [PATCH 02/12] doc: update data model page --- docs/docs/flagsmith-concepts/data-model.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/docs/flagsmith-concepts/data-model.md b/docs/docs/flagsmith-concepts/data-model.md index 1c20db83b5a4..99b42638f36c 100644 --- a/docs/docs/flagsmith-concepts/data-model.md +++ b/docs/docs/flagsmith-concepts/data-model.md @@ -8,7 +8,7 @@ Flagsmith uses a flexible data model to help you manage feature flags and remote Here's a high-level overview of the Flagsmith data model. Fear not - it's not as complex as it looks! -![Flagsmith Data Model](/img/flagsmith-model.svg) +![Image](/img/flagsmith-model.svg) OK let's break this down. @@ -42,11 +42,3 @@ For more info see [Traits](/basic-features/managing-identities.md#identity-trait Segments define a group of users by traits such as login count, device, location or any number of custom defined traits. Similar to individual users, you can override environment defaults for features for a segment. For example, you might show certain features for a "power user" segment. For more info see [Segments](/basic-features/segments.md). - -## Relationships Summary - -- **Organizations** contain **Projects** -- **Projects** contain **Environments** and **Features** -- **Environments** have their own configuration for each **Feature** -- **Identities** belong to an **Environment** and can be related to **Traits** -- **Segments** group **Identities** by rules on **Traits** From dd7058875ebf6e2c88e5c5d587c868352b3d70ea Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Fri, 4 Jul 2025 09:28:27 -0300 Subject: [PATCH 03/12] doc: add platform architecture page --- .../platform-architecture.md | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 docs/docs/flagsmith-concepts/platform-architecture.md diff --git a/docs/docs/flagsmith-concepts/platform-architecture.md b/docs/docs/flagsmith-concepts/platform-architecture.md new file mode 100644 index 000000000000..82853dee40cd --- /dev/null +++ b/docs/docs/flagsmith-concepts/platform-architecture.md @@ -0,0 +1,60 @@ +--- +title: Platform Architecture +sidebar_label: Platform Architecture +sidebar_position: 20 +--- + +# Flagsmith Platform Architecture + +Flagsmith architecture supports a range of deployment models to suit different organisational needs, from fully managed SaaS to self-hosted and on-premises solutions. + +## Conceptual Overview + +The most important components in Flagsmith's architecture are: + +- **Frontend Dashboard**: A web interface for managing projects, environments, feature flags, and user permissions. This is where most configuration and management tasks are performed. +- **Core API**: RESTful API that powers the dashboard and SDKs. These endpoints are used for automation, integrations, and direct management of Flagsmith resources. +- **Edge API**: A globally distributed API for low-latency flag evaluation, especially useful for applications with users around the world. +- **SDKs**: Client libraries (available for many languages and platforms) that connect your applications and services to Flagsmith, enabling real-time feature flag evaluation and remote config. +- **Integrations**: Optional connectors to third-party tools and services (e.g., analytics, notifications, monitoring). These can be configured via the dashboard or API. +- **Database**: Stores all persistent data, such as organisations, projects, features, and audit logs. Managed by Flagsmith in SaaS, but by your team in self-hosted/on-prem deployments. + +The architecture is REST-based, with both SDK clients and the dashboard interacting with the Core API. The platform is designed to be cloud-native, supporting containerization and orchestration for scalability and reliability. + +## Deployment Models + +Flagsmith can be deployed in three main ways, each with conceptual differences in management, control, and responsibility. The following diagrams illustrate the architecture for each model: + +### 1. SaaS (Cloud-Hosted) + +- **Managed by Flagsmith**: No infrastructure to manage; get started instantly. +- **Automatic scaling, security, and updates**: All handled by the Flagsmith team. +- **Global Edge API**: Provides low-latency flag delivery worldwide. +- **Best for**: Teams who want to focus on product development and avoid infrastructure overhead. + +![SaaS Architecture](/img/saas-architecture.svg) + +*The diagram above shows the SaaS deployment model, where all infrastructure is managed by Flagsmith and the Edge API ensures global low-latency delivery.* + +### 2. Self-Hosted (Cloud or Private Cloud) + +- **Managed by your team**: Deploy Flagsmith on your own cloud infrastructure (e.g., AWS, GCP, Azure, DigitalOcean) using Docker, Kubernetes, or other orchestration tools. +- **Full control**: You manage scaling, security, updates, and integrations. +- **Customisation**: Integrate with your own authentication, analytics, and infrastructure. +- **Best for**: Teams with specific compliance, data residency, or custom integration requirements. + +### 3. On-Premises (Enterprise Edition) + +- **Deployed in your private data center or isolated cloud**: For maximum control and data sovereignty. +- **Enterprise features**: Advanced authentication (Okta, LDAP, SAML, ADFS), custom fields, support for additional databases (Oracle, MySQL), and more. +- **Orchestration support**: Kubernetes, OpenShift, AWS ECS, GCP AppEngine, Azure Container Instances, and more. +- **Best for**: Organisations with strict regulatory, security, or data sovereignty requirements. + +![Self-Hosted / On-Prem Architecture](/img/architecture.svg) + +*The diagram above illustrates the Self-Hosted and On-Premises deployment models, where your team manages the infrastructure and has full control over security, compliance, and integrations.* + +## What's next +- [Deployment Options](/deployment) +- [Version Comparison](/version-comparison) +- [Enterprise Edition](/deployment/configuration/enterprise-edition) From 987bd93441f408fd2383a5f793b4bbaacd2a35c6 Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Fri, 4 Jul 2025 09:28:45 -0300 Subject: [PATCH 04/12] doc: add segment concept and reference pages --- .../docs/flagsmith-concepts/segments/index.md | 148 ++++++++++++++++++ .../segments/segment-rule-operators.md | 124 +++++++++++++++ 2 files changed, 272 insertions(+) create mode 100644 docs/docs/flagsmith-concepts/segments/index.md create mode 100644 docs/docs/flagsmith-concepts/segments/segment-rule-operators.md diff --git a/docs/docs/flagsmith-concepts/segments/index.md b/docs/docs/flagsmith-concepts/segments/index.md new file mode 100644 index 000000000000..ce0b81216eb5 --- /dev/null +++ b/docs/docs/flagsmith-concepts/segments/index.md @@ -0,0 +1,148 @@ +--- +title: Segments +sidebar_label: Segments +--- + +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; + +# Segments + +A segment is a subset of [identities](/basic-features/managing-identities.md), defined by a set of rules that match +identity [traits](managing-identities.md#identity-traits). An identity always belongs to a single environment and can +belong to any number of segments. + +Once you have defined a segment, you can create **segment overrides** for features within an environment. A segment +override allows you to control the state of a feature only for identities that belong to a specific segment. This is +similar to how [identity overrides](managing-identities.md#identity-overrides) let you control the state of features for +an explicit set of identities that is known in advance. + +Because segments are driven by identity traits, your application must identify the user when retrieving flags in order +for segment overrides to be applied. If your user is not identified, no overrides will be applied and all flags will be +returned exactly how they are defined in the current environment. + +Segments and segment overrides can be used to implement many scenarios. For example: + +- Test features in production before they are released by overriding them only for internal users or a QA team +- Deliver features only to "power users" who have logged in a certain number of times, have used specific functionality + within your application, or any combination of factors +- Force a group of users into a specific [A/B test](advanced-use/ab-testing.md) variation by overriding weightings on + [multivariate flags](managing-features.md#multi-variate-flags) +- Override behaviour based on the [application version number](/guides-and-examples/mobile-app-versioning.md), e.g. by + using the SemVer rule operators +- Control features based on the time of day, date, weekday, etc. by passing it as a trait when evaluating flags for an + identity + +## Security and privacy + +The Flagsmith API to set user traits, e.g. the `setTraits` method from the JavaScript SDK, does not require +authentication or credentials. This means that users can change their own traits, which could be a security problem if +you are using segments for authorisation or access control. If you must use segments for access control, make sure to +disable the +["Persist traits when using client-side SDK keys" option](system-administration/security.md#preventing-client-sdks-from-setting-traits) +on every environment that needs it, and use server-side SDKs to set traits instead. You can still use client-side SDKs +to read traits and flags derived from segments in this case. + +Segment names and definitions might include sensitive or proprietary information that you do not want to expose to your +users. Because of this, segments are transparent to applications and are not included in API responses when using +[remote evaluation mode](/clients#remote-evaluation). + +Segment definitions _are_ served to clients running in [local evaluation mode](/clients#local-evaluation), as this +allows them to calculate segments without making requests to the Flagsmith API. This is only an implementation detail +and no segment information is exposed when retrieving flags using any SDK method. + +## Creating project or feature-specific segments + +Segments created from the Segments page of the Flagsmith dashboard can be used to override any feature within a single +project. + +To create a segment override, click on a feature in a specific environment and go to the Segment Overrides tab. + +If you need to create a segment that will only ever be used to override a single feature, you can create a +**feature-specific segment** by clicking on "Create Feature-Specific Segment" when creating a segment override. +Feature-specific segments are otherwise functionally identical to project segments. By default, feature-specific +segments are not shown in the Segments page, unless you enable the "Include Feature-Specific" option. + +Once created, project segments cannot be changed into feature-specific segments or vice versa. + +## Order of rules within segments + +Segment rules are evaluated in order, i.e. from top to bottom when viewed in the Flagsmith dashboard. + +For example, consider the following segment: + +1. 10% percentage split +2. `is_subscriber = true` + +This segment would first select 10% of _all_ identities, and then choose subscribers from that cohort. Instead, if we +used the opposite order: + +1. `is_subscriber = true` +2. 10% percentage split + +This would first select all subscriber identities, and then randomly choose 10% of them. + +## Multiple segment overrides for one feature + +If a feature has multiple segment overrides, they are evaluated in order, i.e. from top to bottom when viewed in the +Flagsmith dashboard. The first matching override will be used to determine the state of a feature for a given identity. + +## Flag evaluation precedence + +Identity overrides always take precedence over segment overrides. Simply put, the order of precedence when evaluating a +flag is: + +1. Identity overrides +2. Segment overrides +3. Default value for the current environment + +## Trait data types + +Each individual trait value is always stored as one of the following data types: + +- String +- Boolean +- Integer +- Float + +Values in segment rules, on the other hand, are always stored as strings. When segment rules are evaluated, rule values +will be coerced to be the same type as the trait value. If the rule value cannot be coerced, that rule will evaluate as +false. This provides some flexibility if you ever need to change the data type of a trait, e.g. from boolean to string, +while maintaining backwards and forwards compatibility in your application. + +For example, consider the following code using the JavaScript SDK: + +```javascript +flagsmith.identify('example_user_1234'); +flagsmith.setTrait('accepted_cookies', true); +``` + +The value of the `accepted_cookies` trait will be stored as a boolean for this identity. If you define a segment rule +like `accepted_cookies = true`, the rule value `true` is stored as a string. Because the `accepted_cookies` was stored +as a boolean for this identity, the segment engine will coerce the rule's string value into a boolean, and things will +work as expected. + +Suppose later on you needed to store a third possible state for the trait `accepted_cookies`, for example if users can +partially accept cookies. Your application can start storing this trait as a string without needing to modify your +existing segment: + +```javascript +flagsmith.setTrait('accepted_cookies', 'partial'); +``` + +This would continue to work as expected for identities that already have this trait set as a string value. Always +storing the trait as a string would also work, for example: + +```javascript +flagsmith.setTrait('accepted_cookies', 'true'); +``` + +The following string trait values will evaluate to `true`: + +- `"True"` +- `"true"` +- `"1"` + +## What's next + +- Learn more about [segment rule operators](./segment-rule-operators.md) +- Learn about [targeting and rollouts](/flagsmith-concepts/targeting-and-rollouts.md) diff --git a/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md b/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md new file mode 100644 index 000000000000..dbb1037d6069 --- /dev/null +++ b/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md @@ -0,0 +1,124 @@ +--- +title: Segment Rule Operators +sidebar_label: Segment Rule Operators +--- + +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; + +Segment rule operators in Flagsmith allow you to define how trait values are compared when evaluating segment membership. Note that all operators are case-sensitive. + +| Name | Description | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Exactly Matches (=)` | Trait value is equal to the rule value | +| `Does not match (!=)` | Trait value is not equal to the rule value | +| `% Split` | Identity is in the percentage bucket. [Learn more](?operators=percent#operator-details) | +| `>` | Trait value is greater than the rule value | +| `>=` | Trait value is greater than or equal to the rule value | +| `<` | Trait value is less than the rule value | +| `<=` | Trait value is less than or equal to the rule value | +| `In` | Trait value is equal to any element in a comma-separated list (case-sensitive). [Learn more](?operators=in#operator-details) | +| `Contains` | Rule value is a substring of the trait value | +| `Does not contain` | Rule value is not a substring of the trait value | +| `Matches regex` | Trait value matches the given regular expression | +| `Is set` | Trait value is set for given identity and trait key | +| `Is not set` | Trait value is not set for given identity and trait key | +| `SemVer` | Trait value is compared against the rule value according to [Semantic Versioning](https://semver.org/). [Learn more](?operators=semver#operator-details) | + +### Operator details + + + + +The `In` operator lets you match a trait value against a comma-separated list of values. For example, the segment rule +value might read `21,682,8345`. This would match against a trait value of `682` but not against a trait value of `683` +or `834`. + +The `In` operator can be useful to build segments that represent a specific set of tenants in your application. For +example, you could create a segment with the following rule: `tenant_id In tenant_1,tenant_2,tenant_3` + + + + +[SemVer](https://semver.org/) operators compare semantic version values. Consider the following segment rule: + +`version` `SemVer >=` `4.2.52` + +This segment would include all users that have a `version` trait set to `4.2.52` or greater. For example, any of the +following `version` values would match: + +- `4.2.53` +- `4.10.0` +- `5.0.0` + +Versions are compared as defined by the [Semantic Versioning specification](https://semver.org/#spec-item-11). + + + + +Percentage Split is the only operator that does not require a trait. You can use it to drive +[A/B tests](/advanced-use/ab-testing) and +[staged feature rollouts](/guides-and-examples/staged-feature-rollouts#creating-staged-rollouts). + +Percentage Split deterministically assigns a "bucket" to each identity solely based on its ID and not any traits, +meaning that Segment overrides that use Percentage Split will always result in the same feature value for a given +identity. + +If you create a Segment with a single Percentage Split rule, Identities who are members of that split when the split +value is set to, say, 10% will be guaranteed to also be in that split if it is changed to a value higher than 10%. + +If the Percentage Split is reduced in value, some Identities will be removed from that Percentage Split to maintain the +balance. The algorithm is fairly simple and good to understand - it is +[described here](/guides-and-examples/staged-feature-rollouts#how-does-it-work). + + + + +This operator performs a [modulo operation](https://en.wikipedia.org/wiki/Modulo_operation), which returns the remainder +of dividing a numeric trait value by a given divisor. The operator accepts rule value in the format `divisor|remainder`. +For example: + +`user_id` `%` `2|0` + +This segment will include all identities having an `user_id` trait that is divisible by 2, i.e. even numbers. This is +equivalent to the following expression in many programming languages: + +`user_id % 2 == 0` + + + + +### Minimum SDK versions for local evaluation mode + +When running in local evaluation mode, SDK clients evaluate segment rules locally, which means they must be updated to +support the latest operators. + +If an SDK client tries to evaluate a segment rule that has an unrecognised operator, that rule will silently evaluate to +`false`. The table below lists the minimum required SDK version required by each operator: + +| | Modulo | In | +| ------- | ------ | ----- | +| Python | 2.3.0 | 3.3.0 | +| Java | 5.1.0 | 7.1.0 | +| .NET | 4.2.0 | 5.0.0 | +| Node.js | 2.4.0 | 2.5.0 | +| Ruby | 3.1.0 | 3.2.0 | +| PHP | 3.1.0 | 4.1.0 | +| Go | 2.2.0 | 3.1.0 | +| Rust | 0.2.0 | 1.3.0 | +| Elixir | 1.1.0 | 2.0.0 | + +## Limits + +These are the default limits for segments and rules: + +- 100 segments per project +- 100 segment overrides per environment +- 100 rules per segment override +- 1000 bytes per segment rule value + +See the [documentation on System Limits](system-administration/system-limits.md) for more details. + +## Custom fields + +Optional or required custom fields can be defined when creating or updating segments. +[Learn more](/advanced-use/custom-fields.md) From 243b433b4281dcd20d05b7219749499025ecb638 Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Fri, 4 Jul 2025 09:28:56 -0300 Subject: [PATCH 05/12] doc: add identities concept page --- docs/docs/flagsmith-concepts/identities.md | 146 +++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/docs/flagsmith-concepts/identities.md diff --git a/docs/docs/flagsmith-concepts/identities.md b/docs/docs/flagsmith-concepts/identities.md new file mode 100644 index 000000000000..3addbd610b4f --- /dev/null +++ b/docs/docs/flagsmith-concepts/identities.md @@ -0,0 +1,146 @@ +--- +title: Identities +sidebar_label: Identities +sidebar_position: 30 +--- + +Feature flags are great, but they can be a very blunt tool, only allowing you to enable or disable flags across your +entire user base. In order to target users more precisely, and to be able to perform +[staged feature roll-outs](/guides-and-examples/staged-feature-rollouts.md) or +[A/B and multi-variate tests](/advanced-use/ab-testing.md), you need to _Identify your Users_. + +Identities are created within Flagsmith automatically the first time they are identified from your client SDKs. +Generally you'd make a call to identify a user with a unique string/id whenever they log into your app/site. The SDK +will then send an API message to the Flagsmith API, with the relevant Identity information. + +:::tip + +The SDK part of the Flagsmith API is public by design; the Environment Key is designed to be public. When identifying +users, it is important to use an Identity value that is not easy to guess. For example, if you used an incrementing +integer to identify your users, it would be trivial to request Identities by enumerating this integer. This would +effectively give public access to any user traits that are associated with users. + +We strongly recommend using an unguessable, unidentifiable Identity Key, such as a +[GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), when identifying your users, to prevent +unintentionally leaking Identity trait data. + +::: + +## Identity Overrides + +Once you have uniquely identified a user, you can then override features for that user from your Environment defaults. +For example, you've pushed a feature into production, but the relevant feature flag is still hiding that feature to all +of your users. You can now override that flag for your own user, and test that feature. Once you are happy with +everything, you can roll that feature out to all of your users by enabling the flag itself. + +Identities are specific and individual for each Environment within your project. For example, joe@yourwebsite.com would +be a different identity in your development environment to the one in production, and they can have different features +enabled for each environment. + +## Identity Feature Flags + +By default, Identities receive the default flags for their environment. The main use-case for identities is to be able +to override flags and configs on a per-identity basis. You can do this by navigating to the Users page, finding the User +and modifying their Flags. + +## Identity Traits + +You can also use Flagsmith to store 'Traits' against identities. Traits are key/value pairs that are associated with +individual Identities for a particular Environment. Traits have two purposes outlined below, but the main use case is to +drive [Segments](segments.md). + +:::important + +The maximum size of each individual Trait Value is **_2000 bytes_**. You cannot store more data than that in a single +trait, and the API will return a 500 error if you try to do so. + +::: + +### Using Traits to drive Segments + +Let's say you are working on a mobile app, and you want to control a feature based on the version of the application +that the Identity is using. When you integrate the Flagsmith SDK, you would pass the application version number to the +Flagsmith platform as a trait key/value pair: + +```java +String identifier = "user_512356" +Map traits = new HashMap(); +traits.put("app_version", YourApplication.getVersion()); + +Flags flags = flagsmith.getIdentityFlags(identifier, traits); +``` + +Here we are setting the trait key `app_version` with the value of `YourApplication.getVersion()`.You can now create a +[Segment](segments.md) that is based on the application version and manage features based on the application version. + +Traits are completely free-form. You can store any number of traits, with any relevant information you see fit, in the +platform and then use Segments to control features based on these Trait values. + +## Identity and Trait Storage + +Identities are persisted within the Flagsmith platform, along with any Traits that have been assigned to them. When +Flags are evaluated for an Identity, the full complement of Traits stored within the platform are used, even if they +were not all sent as part of the request. + +This can be useful if, at runtime, your application does not have all the relevant Trait data available for that +particular Identity; any Traits provided will be combined with the Traits stored within Flagsmith before the evaluation +engine runs. + +There are some [exceptions to this rule](/clients#server-side-sdks) with Server Side SDKs running in local evaluation +mode. + +:::info + +Note that, when using our SaaS platform, there might be a short delay from the initial request to write or update traits +for an identity and them being used in subsequent evaluations. + +::: + +### Using Traits as a data-store + +Traits can also be used to store additional data about your users that would be cumbersome to store within your +application. Some possible uses for traits could be: + +- Storing whether the user has accepted a new set of terms and conditions. +- Storing the last viewed page of the application so that you can resume the users place later, across any device. + +Generally if they are lower-value pieces of information about your user, it might be simpler/easier to store them in +Flagsmith rather than in your core application. + +Traits are stored natively as either numbers, strings or booleans. + +## Traits powering Segments + +Traits can be used within your application, but they can also be used to power [Segments](/basic-features/segments.md). + +## Trait Value Data Types + +:::tip + +You can remove a trait by sending `null` as the trait value. + +::: + +Trait values can be stored as one of four different data types: + +- Boolean +- String (max length 2000 bytes) +- Int (32 bit signed) +- Float (typically has a range of around 1E-307 to 1E+308 with a precision of at least 15 digits) + +If you need to store 64 bit integers or very high precision floats we suggest storing them as Strings and then doing the +type conversion within the SDK. + +## Bulk Uploading Identities and Traits + +Identities are lazily created within Flagsmith. There might be instances where you want to push Identity and Trait data +into the platform outside of a user session. We have a +[code example for this](/clients/rest#bulk-uploading-identities-and-traits). + +For more information, see: + +- [Managing Identities](/basic-features/managing-identities) +- [Identity Traits](/basic-features/managing-identities.md#identity-traits)Feature flags are great, but they can be a very blunt tool, only allowing you to enable or disable flags across your +entire user base. In order to target users more precisely, and to be able to perform +[staged feature roll-outs](/guides-and-examples/staged-feature-rollouts.md) or +[A/B and multi-variate tests](/advanced-use/ab-testing.md), you need to _Identify your Users_. From f7f4171e63f8584654ee2c2f234060cae6185b95 Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Fri, 4 Jul 2025 09:29:31 -0300 Subject: [PATCH 06/12] doc: add targeting and rollouts section and overview --- .../targeting-and-rollouts/index.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/docs/flagsmith-concepts/targeting-and-rollouts/index.md diff --git a/docs/docs/flagsmith-concepts/targeting-and-rollouts/index.md b/docs/docs/flagsmith-concepts/targeting-and-rollouts/index.md new file mode 100644 index 000000000000..3d7add020f34 --- /dev/null +++ b/docs/docs/flagsmith-concepts/targeting-and-rollouts/index.md @@ -0,0 +1,66 @@ +--- +title: Targeting and Rollouts +description: Conceptual overview of targeting and rollout operations for feature flags in Flagsmith. +sidebar_label: Targeting & Rollouts +--- + +# Targeting and Rollouts: Concepts & Overview + +Flagsmith provides powerful targeting and rollout capabilities to help you deliver features safely, progressively, and with maximum control. This page explains the concepts and available operations for targeting and rollouts. + +## What is Targeting? + +**Targeting** is the practice of controlling feature flag states for specific users or groups, rather than for all users at once. This enables you to: +- Release features to internal users, beta testers, or select customers before a full launch. +- Target features to users with specific traits (such as geography, subscription level, device type, or app version). +- Run experiments (A/B or multivariate tests) by segmenting your user base. +- Roll out features gradually to reduce risk and monitor impact. + +## What is a Rollout? + +A **rollout** is a staged release of a feature to a subset of users, often increasing the percentage of users over time. Rollouts help you: +- Minimize the impact of bugs or regressions by limiting exposure. +- Monitor performance and user feedback before a full launch. +- Quickly disable ("kill switch") a feature for affected users if issues arise. + +## Targeting and Rollout Operations in Flagsmith + +Flagsmith supports several operations for targeting and rollouts. + +### Environment-level Flags +- Control a feature for all users in a given environment (e.g., development, staging, production). +- Useful for broad control and environment-specific testing. + +### Identity Targeting +- Override feature flags for individual users ("identities"). +- Enables internal testing, QA, customer support, or personalized experiences at the user level. + +### Segment Targeting +- Define **segments**—groups of users matching rules based on traits (e.g., location, plan, app version, usage). +- Override feature flags for all users in a segment. +- Segments can be combined with percentage rollouts and other rules for advanced targeting. + +### Staged Rollouts +- Gradually enable a feature for a percentage of users, either globally or within a segment. +- Useful for canary releases, progressive delivery, and experimentation. +- Flagsmith uses a deterministic hashing algorithm to ensure consistent user experiences during rollouts. + +### Multivariate Flags +- Assign users to different flag "variants" (e.g., for A/B/n testing) based on defined weightings. +- Can be combined with targeting and rollouts for advanced experiments and optimization. + +## Why Use Targeting and Rollouts? + +- **Reduce risk:** Catch issues early by exposing new features to a small group first. +- **Personalize experiences:** Deliver features to users who will benefit most. +- **Experiment and optimize:** Test multiple variants and measure impact. +- **Comply with requirements:** Target features to specific regions, plans, or device types. +- **Respond quickly:** Instantly disable features for affected users if problems arise. + +## Learn More + +- [Managing Identities](/basic-features/managing-identities.md) +- [Segments & Segment Targeting](/basic-features/segments.md) +- [Staged Feature Rollouts](/guides-and-examples/staged-feature-rollouts.md) +- [A/B and Multivariate Testing](/advanced-use/ab-testing.md) +- [Managing Features & Multivariate Flags](/basic-features/managing-features.md) From 72247f3e191c1a70b72a4981367499c45af48259 Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Thu, 17 Jul 2025 08:45:14 -0300 Subject: [PATCH 07/12] doc: fix english version --- docs/docs/flagsmith-concepts/data-model.md | 18 ++--- docs/docs/flagsmith-concepts/identities.md | 79 +++++-------------- .../platform-architecture.md | 8 +- .../docs/flagsmith-concepts/segments/index.md | 75 +++++------------- .../segments/segment-rule-operators.md | 45 ++++------- .../targeting-and-rollouts/index.md | 14 ++-- 6 files changed, 74 insertions(+), 165 deletions(-) diff --git a/docs/docs/flagsmith-concepts/data-model.md b/docs/docs/flagsmith-concepts/data-model.md index 99b42638f36c..6dc75d46b22f 100644 --- a/docs/docs/flagsmith-concepts/data-model.md +++ b/docs/docs/flagsmith-concepts/data-model.md @@ -12,8 +12,8 @@ Here's a high-level overview of the Flagsmith data model. Fear not - it's not as OK let's break this down. -### Organizations -Organizations allow you and other team members to manage projects and their features. A user can be a member of multiple organizations. +### Organisations +Organisations allow you and other team members to manage projects and their features. A user can be a member of multiple organisations. ### Projects Projects contain one or more Environments that share a single set of Features. Organisations can have any number of Projects. @@ -27,18 +27,18 @@ Features are shared across all Environments within a Project, but their values/s ### Identities Identities are a particular user registration for one of your Project's Environments. Registering identities within the client application allows you to manage features for individual users. Identity features can be overridden from your environment defaults. For example, joe@yourwebsite.com would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment. -For more info see [Identities](/basic-features/managing-identities). +For more information, see [Identities](/basic-features/managing-identities). ### Traits -You can store any number of Traits against an Identity. Traits are key:value pairs that can store any type of data. Some examples of traits that you might store against an Identity might be: +You can store any number of Traits against an Identity. Traits are key-value pairs that can store any type of data. Some examples of traits that you might store against an Identity include: - The number of times the user has logged in. -- If they have accepted the application terms and conditions. +- Whether they have accepted the application terms and conditions. - Their preferred application theme. -- If they have performed certain actions within your application. +- Whether they have performed certain actions within your application. -For more info see [Traits](/basic-features/managing-identities.md#identity-traits). +For more information, see [Traits](/basic-features/managing-identities.md#identity-traits). ### Segments -Segments define a group of users by traits such as login count, device, location or any number of custom defined traits. Similar to individual users, you can override environment defaults for features for a segment. For example, you might show certain features for a "power user" segment. +Segments define a group of users by traits such as login count, device, location, or any number of custom-defined traits. Similar to individual users, you can override environment defaults for features for a segment. For example, you might show certain features for a "power user" segment. -For more info see [Segments](/basic-features/segments.md). +For more information, see [Segments](/basic-features/segments.md). diff --git a/docs/docs/flagsmith-concepts/identities.md b/docs/docs/flagsmith-concepts/identities.md index 3addbd610b4f..ad98bce49ed6 100644 --- a/docs/docs/flagsmith-concepts/identities.md +++ b/docs/docs/flagsmith-concepts/identities.md @@ -4,63 +4,42 @@ sidebar_label: Identities sidebar_position: 30 --- -Feature flags are great, but they can be a very blunt tool, only allowing you to enable or disable flags across your -entire user base. In order to target users more precisely, and to be able to perform -[staged feature roll-outs](/guides-and-examples/staged-feature-rollouts.md) or -[A/B and multi-variate tests](/advanced-use/ab-testing.md), you need to _Identify your Users_. +Feature flags are great, but they can be a very blunt tool, only allowing you to enable or disable flags across your entire user base. In order to target users more precisely, and to be able to perform [staged feature roll-outs](/guides-and-examples/staged-feature-rollouts.md) or [A/B and multivariate tests](/advanced-use/ab-testing.md), you need to _Identify your Users_. -Identities are created within Flagsmith automatically the first time they are identified from your client SDKs. -Generally you'd make a call to identify a user with a unique string/id whenever they log into your app/site. The SDK -will then send an API message to the Flagsmith API, with the relevant Identity information. +Identities are created within Flagsmith automatically the first time they are identified from your client SDKs. Generally, you would make a call to identify a user with a unique string or identifier whenever they log into your application or site. The SDK will then send an API message to the Flagsmith API, with the relevant Identity information. :::tip -The SDK part of the Flagsmith API is public by design; the Environment Key is designed to be public. When identifying -users, it is important to use an Identity value that is not easy to guess. For example, if you used an incrementing -integer to identify your users, it would be trivial to request Identities by enumerating this integer. This would -effectively give public access to any user traits that are associated with users. +The SDK part of the Flagsmith API is public by design; the Environment Key is intended to be public. When identifying users, it is important to use an Identity value that is not easy to guess. For example, if you used an incrementing integer to identify your users, it would be trivial to request Identities by enumerating this integer. This would effectively provide public access to any user traits that are associated with users. -We strongly recommend using an unguessable, unidentifiable Identity Key, such as a -[GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), when identifying your users, to prevent -unintentionally leaking Identity trait data. +We strongly recommend using an unguessable, unidentifiable Identity Key, such as a [GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), when identifying your users, to prevent unintentionally leaking Identity trait data. ::: ## Identity Overrides -Once you have uniquely identified a user, you can then override features for that user from your Environment defaults. -For example, you've pushed a feature into production, but the relevant feature flag is still hiding that feature to all -of your users. You can now override that flag for your own user, and test that feature. Once you are happy with -everything, you can roll that feature out to all of your users by enabling the flag itself. +Once you have uniquely identified a user, you can then override features for that user from your Environment defaults. For example, you've pushed a feature into production, but the relevant feature flag is still hiding that feature from all of your users. You can now override that flag for your own user, and test that feature. Once you are happy with everything, you can roll that feature out to all of your users by enabling the flag itself. -Identities are specific and individual for each Environment within your project. For example, joe@yourwebsite.com would -be a different identity in your development environment to the one in production, and they can have different features -enabled for each environment. +Identities are specific and individual for each Environment within your project. For example, joe@yourwebsite.com would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment. ## Identity Feature Flags -By default, Identities receive the default flags for their environment. The main use-case for identities is to be able -to override flags and configs on a per-identity basis. You can do this by navigating to the Users page, finding the User +By default, Identities receive the default flags for their environment. The main use-case for identities is to be able to override flags and configs on a per-identity basis. You can do this by navigating to the Users page, finding the User and modifying their Flags. ## Identity Traits -You can also use Flagsmith to store 'Traits' against identities. Traits are key/value pairs that are associated with -individual Identities for a particular Environment. Traits have two purposes outlined below, but the main use case is to -drive [Segments](segments.md). +You can also use Flagsmith to store 'Traits' against identities. Traits are key/value pairs that are associated with individual Identities for a particular Environment. Traits have two purposes outlined below, but the main use case is to drive [Segments](segments.md). :::important -The maximum size of each individual Trait Value is **_2000 bytes_**. You cannot store more data than that in a single -trait, and the API will return a 500 error if you try to do so. +The maximum size of each individual Trait Value is **_2000 bytes_**. You cannot store more data than that in a single trait, and the API will return a 500 error if you try to do so. ::: ### Using Traits to drive Segments -Let's say you are working on a mobile app, and you want to control a feature based on the version of the application -that the Identity is using. When you integrate the Flagsmith SDK, you would pass the application version number to the -Flagsmith platform as a trait key/value pair: +Let's say you are working on a mobile app, and you want to control a feature based on the version of the application that the Identity is using. When you integrate the Flagsmith SDK, you would pass the application version number to the Flagsmith platform as a trait key/value pair: ```java String identifier = "user_512356" @@ -70,42 +49,32 @@ traits.put("app_version", YourApplication.getVersion()); Flags flags = flagsmith.getIdentityFlags(identifier, traits); ``` -Here we are setting the trait key `app_version` with the value of `YourApplication.getVersion()`.You can now create a -[Segment](segments.md) that is based on the application version and manage features based on the application version. +Here we are setting the trait key `app_version` with the value of `YourApplication.getVersion()`.You can now create a [Segment](segments.md) that is based on the application version and manage features based on the application version. -Traits are completely free-form. You can store any number of traits, with any relevant information you see fit, in the -platform and then use Segments to control features based on these Trait values. +Traits are completely free-form. You can store any number of traits, with any relevant information you see fit, in the platform and then use Segments to control features based on these Trait values. ## Identity and Trait Storage -Identities are persisted within the Flagsmith platform, along with any Traits that have been assigned to them. When -Flags are evaluated for an Identity, the full complement of Traits stored within the platform are used, even if they -were not all sent as part of the request. +Identities are persisted within the Flagsmith platform, along with any Traits that have been assigned to them. When Flags are evaluated for an Identity, the full complement of Traits stored within the platform are used, even if they were not all sent as part of the request. -This can be useful if, at runtime, your application does not have all the relevant Trait data available for that -particular Identity; any Traits provided will be combined with the Traits stored within Flagsmith before the evaluation -engine runs. +This can be useful if, at runtime, your application does not have all the relevant Trait data available for that particular Identity; any Traits provided will be combined with the Traits stored within Flagsmith before the evaluation engine runs. -There are some [exceptions to this rule](/clients#server-side-sdks) with Server Side SDKs running in local evaluation -mode. +There are some [exceptions to this rule](/clients#server-side-sdks) with Server Side SDKs running in local evaluation mode. :::info -Note that, when using our SaaS platform, there might be a short delay from the initial request to write or update traits -for an identity and them being used in subsequent evaluations. +Note that, when using our SaaS platform, there might be a short delay from the initial request to write or update traits for an identity and them being used in subsequent evaluations. ::: ### Using Traits as a data-store -Traits can also be used to store additional data about your users that would be cumbersome to store within your -application. Some possible uses for traits could be: +Traits can also be used to store additional data about your users that would be cumbersome to store within your application. Some possible uses for traits could be: - Storing whether the user has accepted a new set of terms and conditions. - Storing the last viewed page of the application so that you can resume the users place later, across any device. -Generally if they are lower-value pieces of information about your user, it might be simpler/easier to store them in -Flagsmith rather than in your core application. +Generally if they are lower-value pieces of information about your user, it might be simpler/easier to store them in Flagsmith rather than in your core application. Traits are stored natively as either numbers, strings or booleans. @@ -128,19 +97,13 @@ Trait values can be stored as one of four different data types: - Int (32 bit signed) - Float (typically has a range of around 1E-307 to 1E+308 with a precision of at least 15 digits) -If you need to store 64 bit integers or very high precision floats we suggest storing them as Strings and then doing the -type conversion within the SDK. +If you need to store 64 bit integers or very high precision floats we suggest storing them as Strings and then doing the type conversion within the SDK. ## Bulk Uploading Identities and Traits -Identities are lazily created within Flagsmith. There might be instances where you want to push Identity and Trait data -into the platform outside of a user session. We have a -[code example for this](/clients/rest#bulk-uploading-identities-and-traits). +Identities are lazily created within Flagsmith. There might be instances where you want to push Identity and Trait data into the platform outside of a user session. We have a [code example for this](/clients/rest#bulk-uploading-identities-and-traits). For more information, see: - [Managing Identities](/basic-features/managing-identities) -- [Identity Traits](/basic-features/managing-identities.md#identity-traits)Feature flags are great, but they can be a very blunt tool, only allowing you to enable or disable flags across your -entire user base. In order to target users more precisely, and to be able to perform -[staged feature roll-outs](/guides-and-examples/staged-feature-rollouts.md) or -[A/B and multi-variate tests](/advanced-use/ab-testing.md), you need to _Identify your Users_. + diff --git a/docs/docs/flagsmith-concepts/platform-architecture.md b/docs/docs/flagsmith-concepts/platform-architecture.md index 82853dee40cd..14a3bce0f290 100644 --- a/docs/docs/flagsmith-concepts/platform-architecture.md +++ b/docs/docs/flagsmith-concepts/platform-architecture.md @@ -15,11 +15,11 @@ The most important components in Flagsmith's architecture are: - **Frontend Dashboard**: A web interface for managing projects, environments, feature flags, and user permissions. This is where most configuration and management tasks are performed. - **Core API**: RESTful API that powers the dashboard and SDKs. These endpoints are used for automation, integrations, and direct management of Flagsmith resources. - **Edge API**: A globally distributed API for low-latency flag evaluation, especially useful for applications with users around the world. -- **SDKs**: Client libraries (available for many languages and platforms) that connect your applications and services to Flagsmith, enabling real-time feature flag evaluation and remote config. +- **SDKs**: Client libraries (available for many languages and platforms) that connect your applications and services to Flagsmith, enabling real-time feature flag evaluation and remote configuration. - **Integrations**: Optional connectors to third-party tools and services (e.g., analytics, notifications, monitoring). These can be configured via the dashboard or API. - **Database**: Stores all persistent data, such as organisations, projects, features, and audit logs. Managed by Flagsmith in SaaS, but by your team in self-hosted/on-prem deployments. -The architecture is REST-based, with both SDK clients and the dashboard interacting with the Core API. The platform is designed to be cloud-native, supporting containerization and orchestration for scalability and reliability. +The architecture is REST-based, with both SDK clients and the dashboard interacting with the Core API. The platform is designed to be cloud-native, supporting containerisation and orchestration for scalability and reliability. ## Deployment Models @@ -30,7 +30,7 @@ Flagsmith can be deployed in three main ways, each with conceptual differences i - **Managed by Flagsmith**: No infrastructure to manage; get started instantly. - **Automatic scaling, security, and updates**: All handled by the Flagsmith team. - **Global Edge API**: Provides low-latency flag delivery worldwide. -- **Best for**: Teams who want to focus on product development and avoid infrastructure overhead. +- **Best for**: Teams who wish to focus on product development and avoid infrastructure overhead. ![SaaS Architecture](/img/saas-architecture.svg) @@ -45,7 +45,7 @@ Flagsmith can be deployed in three main ways, each with conceptual differences i ### 3. On-Premises (Enterprise Edition) -- **Deployed in your private data center or isolated cloud**: For maximum control and data sovereignty. +- **Deployed in your private data centre or isolated cloud**: For maximum control and data sovereignty. - **Enterprise features**: Advanced authentication (Okta, LDAP, SAML, ADFS), custom fields, support for additional databases (Oracle, MySQL), and more. - **Orchestration support**: Kubernetes, OpenShift, AWS ECS, GCP AppEngine, Azure Container Instances, and more. - **Best for**: Organisations with strict regulatory, security, or data sovereignty requirements. diff --git a/docs/docs/flagsmith-concepts/segments/index.md b/docs/docs/flagsmith-concepts/segments/index.md index ce0b81216eb5..6a7967f85db7 100644 --- a/docs/docs/flagsmith-concepts/segments/index.md +++ b/docs/docs/flagsmith-concepts/segments/index.md @@ -7,60 +7,35 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Segments -A segment is a subset of [identities](/basic-features/managing-identities.md), defined by a set of rules that match -identity [traits](managing-identities.md#identity-traits). An identity always belongs to a single environment and can -belong to any number of segments. +A segment is a subset of [identities](/basic-features/managing-identities.md), defined by a set of rules that match identity [traits](managing-identities.md#identity-traits). An identity always belongs to a single environment and can belong to any number of segments. -Once you have defined a segment, you can create **segment overrides** for features within an environment. A segment -override allows you to control the state of a feature only for identities that belong to a specific segment. This is -similar to how [identity overrides](managing-identities.md#identity-overrides) let you control the state of features for -an explicit set of identities that is known in advance. +Once you have defined a segment, you can create **segment overrides** for features within an environment. A segment override allows you to control the state of a feature only for identities that belong to a specific segment. This is similar to how [identity overrides](managing-identities.md#identity-overrides) let you control the state of features for an explicit set of identities that is known in advance. -Because segments are driven by identity traits, your application must identify the user when retrieving flags in order -for segment overrides to be applied. If your user is not identified, no overrides will be applied and all flags will be -returned exactly how they are defined in the current environment. +Because segments are driven by identity traits, your application must identify the user when retrieving flags in order for segment overrides to be applied. If your user is not identified, no overrides will be applied and all flags will be returned exactly as they are defined in the current environment. Segments and segment overrides can be used to implement many scenarios. For example: - Test features in production before they are released by overriding them only for internal users or a QA team -- Deliver features only to "power users" who have logged in a certain number of times, have used specific functionality - within your application, or any combination of factors -- Force a group of users into a specific [A/B test](advanced-use/ab-testing.md) variation by overriding weightings on - [multivariate flags](managing-features.md#multi-variate-flags) -- Override behaviour based on the [application version number](/guides-and-examples/mobile-app-versioning.md), e.g. by - using the SemVer rule operators -- Control features based on the time of day, date, weekday, etc. by passing it as a trait when evaluating flags for an - identity +- Deliver features only to "power users" who have logged in a certain number of times, have used specific functionality within your application, or any combination of factors +- Force a group of users into a specific [A/B test](advanced-use/ab-testing.md) variation by overriding weightings on [multivariate flags](managing-features.md#multi-variate-flags) +- Override behaviour based on the [application version number](/guides-and-examples/mobile-app-versioning.md), e.g. by using the SemVer rule operators +- Control features based on the time of day, date, weekday, etc. by passing it as a trait when evaluating flags for an identity ## Security and privacy -The Flagsmith API to set user traits, e.g. the `setTraits` method from the JavaScript SDK, does not require -authentication or credentials. This means that users can change their own traits, which could be a security problem if -you are using segments for authorisation or access control. If you must use segments for access control, make sure to -disable the -["Persist traits when using client-side SDK keys" option](system-administration/security.md#preventing-client-sdks-from-setting-traits) -on every environment that needs it, and use server-side SDKs to set traits instead. You can still use client-side SDKs -to read traits and flags derived from segments in this case. +The Flagsmith API to set user traits, e.g. the `setTraits` method from the JavaScript SDK, does not require authentication or credentials. This means that users can change their own traits, which could be a security problem if you are using segments for authorisation or access control. If you must use segments for access control, make sure to disable the ["Persist traits when using client-side SDK keys" option](system-administration/security.md#preventing-client-sdks-from-setting-traits) on every environment that needs it, and use server-side SDKs to set traits instead. You can still use client-side SDKs to read traits and flags derived from segments in this case. -Segment names and definitions might include sensitive or proprietary information that you do not want to expose to your -users. Because of this, segments are transparent to applications and are not included in API responses when using -[remote evaluation mode](/clients#remote-evaluation). +Segment names and definitions might include sensitive or proprietary information that you do not wish to expose to your users. Because of this, segments are transparent to applications and are not included in API responses when using [remote evaluation mode](/clients#remote-evaluation). -Segment definitions _are_ served to clients running in [local evaluation mode](/clients#local-evaluation), as this -allows them to calculate segments without making requests to the Flagsmith API. This is only an implementation detail -and no segment information is exposed when retrieving flags using any SDK method. +Segment definitions _are_ served to clients running in [local evaluation mode](/clients#local-evaluation), as this allows them to calculate segments without making requests to the Flagsmith API. This is only an implementation detail and no segment information is exposed when retrieving flags using any SDK method. ## Creating project or feature-specific segments -Segments created from the Segments page of the Flagsmith dashboard can be used to override any feature within a single -project. +Segments created from the Segments page of the Flagsmith dashboard can be used to override any feature within a single project. To create a segment override, click on a feature in a specific environment and go to the Segment Overrides tab. -If you need to create a segment that will only ever be used to override a single feature, you can create a -**feature-specific segment** by clicking on "Create Feature-Specific Segment" when creating a segment override. -Feature-specific segments are otherwise functionally identical to project segments. By default, feature-specific -segments are not shown in the Segments page, unless you enable the "Include Feature-Specific" option. +If you need to create a segment that will only ever be used to override a single feature, you can create a **feature-specific segment** by clicking on "Create Feature-Specific Segment" when creating a segment override. Feature-specific segments are otherwise functionally identical to project segments. By default, feature-specific segments are not shown in the Segments page, unless you enable the "Include Feature-Specific" option. Once created, project segments cannot be changed into feature-specific segments or vice versa. @@ -73,8 +48,7 @@ For example, consider the following segment: 1. 10% percentage split 2. `is_subscriber = true` -This segment would first select 10% of _all_ identities, and then choose subscribers from that cohort. Instead, if we -used the opposite order: +This segment would first select 10% of _all_ identities, and then choose subscribers from that cohort. Instead, if we used the opposite order: 1. `is_subscriber = true` 2. 10% percentage split @@ -83,13 +57,11 @@ This would first select all subscriber identities, and then randomly choose 10% ## Multiple segment overrides for one feature -If a feature has multiple segment overrides, they are evaluated in order, i.e. from top to bottom when viewed in the -Flagsmith dashboard. The first matching override will be used to determine the state of a feature for a given identity. +If a feature has multiple segment overrides, they are evaluated in order, i.e. from top to bottom when viewed in the Flagsmith dashboard. The first matching override will be used to determine the state of a feature for a given identity. ## Flag evaluation precedence -Identity overrides always take precedence over segment overrides. Simply put, the order of precedence when evaluating a -flag is: +Identity overrides always take precedence over segment overrides. Simply put, the order of precedence when evaluating a flag is: 1. Identity overrides 2. Segment overrides @@ -104,10 +76,7 @@ Each individual trait value is always stored as one of the following data types: - Integer - Float -Values in segment rules, on the other hand, are always stored as strings. When segment rules are evaluated, rule values -will be coerced to be the same type as the trait value. If the rule value cannot be coerced, that rule will evaluate as -false. This provides some flexibility if you ever need to change the data type of a trait, e.g. from boolean to string, -while maintaining backwards and forwards compatibility in your application. +Values in segment rules, on the other hand, are always stored as strings. When segment rules are evaluated, rule values will be coerced to be the same type as the trait value. If the rule value cannot be coerced, that rule will evaluate as false. This provides some flexibility if you ever need to change the data type of a trait, e.g. from boolean to string, while maintaining backwards and forwards compatibility in your application. For example, consider the following code using the JavaScript SDK: @@ -116,21 +85,15 @@ flagsmith.identify('example_user_1234'); flagsmith.setTrait('accepted_cookies', true); ``` -The value of the `accepted_cookies` trait will be stored as a boolean for this identity. If you define a segment rule -like `accepted_cookies = true`, the rule value `true` is stored as a string. Because the `accepted_cookies` was stored -as a boolean for this identity, the segment engine will coerce the rule's string value into a boolean, and things will -work as expected. +The value of the `accepted_cookies` trait will be stored as a boolean for this identity. If you define a segment rule like `accepted_cookies = true`, the rule value `true` is stored as a string. Because the `accepted_cookies` was stored as a boolean for this identity, the segment engine will coerce the rule's string value into a boolean, and things will work as expected. -Suppose later on you needed to store a third possible state for the trait `accepted_cookies`, for example if users can -partially accept cookies. Your application can start storing this trait as a string without needing to modify your -existing segment: +Suppose later on you needed to store a third possible state for the trait `accepted_cookies`, for example if users can partially accept cookies. Your application can start storing this trait as a string without needing to modify your existing segment: ```javascript flagsmith.setTrait('accepted_cookies', 'partial'); ``` -This would continue to work as expected for identities that already have this trait set as a string value. Always -storing the trait as a string would also work, for example: +This would continue to work as expected for identities that already have this trait set as a string value. Always storing the trait as a string would also work, for example: ```javascript flagsmith.setTrait('accepted_cookies', 'true'); diff --git a/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md b/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md index dbb1037d6069..8201da859999 100644 --- a/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md +++ b/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md @@ -20,8 +20,8 @@ Segment rule operators in Flagsmith allow you to define how trait values are com | `Contains` | Rule value is a substring of the trait value | | `Does not contain` | Rule value is not a substring of the trait value | | `Matches regex` | Trait value matches the given regular expression | -| `Is set` | Trait value is set for given identity and trait key | -| `Is not set` | Trait value is not set for given identity and trait key | +| `Is set` | Trait value is set for the given identity and trait key | +| `Is not set` | Trait value is not set for the given identity and trait key | | `SemVer` | Trait value is compared against the rule value according to [Semantic Versioning](https://semver.org/). [Learn more](?operators=semver#operator-details) | ### Operator details @@ -29,12 +29,9 @@ Segment rule operators in Flagsmith allow you to define how trait values are com -The `In` operator lets you match a trait value against a comma-separated list of values. For example, the segment rule -value might read `21,682,8345`. This would match against a trait value of `682` but not against a trait value of `683` -or `834`. +The `In` operator enables you to match a trait value against a comma-separated list of values. For example, the segment rule value might read `21,682,8345`. This would match against a trait value of `682` but not against a trait value of `683` or `834`. -The `In` operator can be useful to build segments that represent a specific set of tenants in your application. For -example, you could create a segment with the following rule: `tenant_id In tenant_1,tenant_2,tenant_3` +The `In` operator can be useful for building segments that represent a specific set of tenants in your application. For example, you could create a segment with the following rule: `tenant_id In tenant_1,tenant_2,tenant_3` @@ -43,8 +40,7 @@ example, you could create a segment with the following rule: `tenant_id In tenan `version` `SemVer >=` `4.2.52` -This segment would include all users that have a `version` trait set to `4.2.52` or greater. For example, any of the -following `version` values would match: +This segment would include all users that have a `version` trait set to `4.2.52` or greater. For example, any of the following `version` values would match: - `4.2.53` - `4.10.0` @@ -55,32 +51,22 @@ Versions are compared as defined by the [Semantic Versioning specification](http -Percentage Split is the only operator that does not require a trait. You can use it to drive -[A/B tests](/advanced-use/ab-testing) and -[staged feature rollouts](/guides-and-examples/staged-feature-rollouts#creating-staged-rollouts). +Percentage Split is the only operator that does not require a trait. You can use it to drive [A/B tests](/advanced-use/ab-testing) and [staged feature rollouts](/guides-and-examples/staged-feature-rollouts#creating-staged-rollouts). -Percentage Split deterministically assigns a "bucket" to each identity solely based on its ID and not any traits, -meaning that Segment overrides that use Percentage Split will always result in the same feature value for a given -identity. +Percentage Split deterministically assigns a "bucket" to each identity solely based on its ID and not any traits, meaning that Segment overrides that use Percentage Split will always result in the same feature value for a given identity. -If you create a Segment with a single Percentage Split rule, Identities who are members of that split when the split -value is set to, say, 10% will be guaranteed to also be in that split if it is changed to a value higher than 10%. +If you create a Segment with a single Percentage Split rule, Identities who are members of that split when the split value is set to, say, 10% will be guaranteed to also be in that split if it is changed to a value higher than 10%. -If the Percentage Split is reduced in value, some Identities will be removed from that Percentage Split to maintain the -balance. The algorithm is fairly simple and good to understand - it is -[described here](/guides-and-examples/staged-feature-rollouts#how-does-it-work). +If the Percentage Split is reduced in value, some Identities will be removed from that Percentage Split to maintain the balance. The algorithm is fairly simple and good to understand – it is [described here](/guides-and-examples/staged-feature-rollouts#how-does-it-work). -This operator performs a [modulo operation](https://en.wikipedia.org/wiki/Modulo_operation), which returns the remainder -of dividing a numeric trait value by a given divisor. The operator accepts rule value in the format `divisor|remainder`. -For example: +This operator performs a [modulo operation](https://en.wikipedia.org/wiki/Modulo_operation), which returns the remainder of dividing a numeric trait value by a given divisor. The operator accepts rule value in the format `divisor|remainder`. For example: `user_id` `%` `2|0` -This segment will include all identities having an `user_id` trait that is divisible by 2, i.e. even numbers. This is -equivalent to the following expression in many programming languages: +This segment will include all identities having a `user_id` trait that is divisible by 2, i.e. even numbers. This is equivalent to the following expression in many programming languages: `user_id % 2 == 0` @@ -89,11 +75,9 @@ equivalent to the following expression in many programming languages: ### Minimum SDK versions for local evaluation mode -When running in local evaluation mode, SDK clients evaluate segment rules locally, which means they must be updated to -support the latest operators. +When running in local evaluation mode, SDK clients evaluate segment rules locally, which means they must be updated to support the latest operators. -If an SDK client tries to evaluate a segment rule that has an unrecognised operator, that rule will silently evaluate to -`false`. The table below lists the minimum required SDK version required by each operator: +If an SDK client tries to evaluate a segment rule that has an unrecognised operator, that rule will silently evaluate to `false`. The table below lists the minimum required SDK version required by each operator: | | Modulo | In | | ------- | ------ | ----- | @@ -120,5 +104,4 @@ See the [documentation on System Limits](system-administration/system-limits.md) ## Custom fields -Optional or required custom fields can be defined when creating or updating segments. -[Learn more](/advanced-use/custom-fields.md) +Optional or required custom fields can be defined when creating or updating segments. [Learn more](/advanced-use/custom-fields.md) diff --git a/docs/docs/flagsmith-concepts/targeting-and-rollouts/index.md b/docs/docs/flagsmith-concepts/targeting-and-rollouts/index.md index 3d7add020f34..ebb12a9d8ff3 100644 --- a/docs/docs/flagsmith-concepts/targeting-and-rollouts/index.md +++ b/docs/docs/flagsmith-concepts/targeting-and-rollouts/index.md @@ -12,14 +12,14 @@ Flagsmith provides powerful targeting and rollout capabilities to help you deliv **Targeting** is the practice of controlling feature flag states for specific users or groups, rather than for all users at once. This enables you to: - Release features to internal users, beta testers, or select customers before a full launch. -- Target features to users with specific traits (such as geography, subscription level, device type, or app version). +- Target features to users with specific traits (such as geography, subscription level, device type, or application version). - Run experiments (A/B or multivariate tests) by segmenting your user base. - Roll out features gradually to reduce risk and monitor impact. ## What is a Rollout? -A **rollout** is a staged release of a feature to a subset of users, often increasing the percentage of users over time. Rollouts help you: -- Minimize the impact of bugs or regressions by limiting exposure. +A **rollout** is a staged release of a feature to a subset of users, often increasing the percentage of users over time. Rollouts help you to: +- Minimise the impact of bugs or regressions by limiting exposure. - Monitor performance and user feedback before a full launch. - Quickly disable ("kill switch") a feature for affected users if issues arise. @@ -33,7 +33,7 @@ Flagsmith supports several operations for targeting and rollouts. ### Identity Targeting - Override feature flags for individual users ("identities"). -- Enables internal testing, QA, customer support, or personalized experiences at the user level. +- Enables internal testing, QA, customer support, or personalised experiences at the user level. ### Segment Targeting - Define **segments**—groups of users matching rules based on traits (e.g., location, plan, app version, usage). @@ -47,13 +47,13 @@ Flagsmith supports several operations for targeting and rollouts. ### Multivariate Flags - Assign users to different flag "variants" (e.g., for A/B/n testing) based on defined weightings. -- Can be combined with targeting and rollouts for advanced experiments and optimization. +- Can be combined with targeting and rollouts for advanced experiments and optimisation. ## Why Use Targeting and Rollouts? - **Reduce risk:** Catch issues early by exposing new features to a small group first. -- **Personalize experiences:** Deliver features to users who will benefit most. -- **Experiment and optimize:** Test multiple variants and measure impact. +- **Personalise experiences:** Deliver features to users who will benefit most. +- **Experiment and optimise:** Test multiple variants and measure impact. - **Comply with requirements:** Target features to specific regions, plans, or device types. - **Respond quickly:** Instantly disable features for affected users if problems arise. From 2ccce4c6b52bdd1556574806a86f5905bf1b1e1e Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Mon, 28 Jul 2025 09:06:40 -0300 Subject: [PATCH 08/12] doc: fix links --- docs/docs/flagsmith-concepts/identities.md | 4 ++-- docs/docs/flagsmith-concepts/segments/index.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/flagsmith-concepts/identities.md b/docs/docs/flagsmith-concepts/identities.md index ad98bce49ed6..355b3b76877c 100644 --- a/docs/docs/flagsmith-concepts/identities.md +++ b/docs/docs/flagsmith-concepts/identities.md @@ -29,7 +29,7 @@ and modifying their Flags. ## Identity Traits -You can also use Flagsmith to store 'Traits' against identities. Traits are key/value pairs that are associated with individual Identities for a particular Environment. Traits have two purposes outlined below, but the main use case is to drive [Segments](segments.md). +You can also use Flagsmith to store 'Traits' against identities. Traits are key/value pairs that are associated with individual Identities for a particular Environment. Traits have two purposes outlined below, but the main use case is to drive [Segments](./segments). :::important @@ -49,7 +49,7 @@ traits.put("app_version", YourApplication.getVersion()); Flags flags = flagsmith.getIdentityFlags(identifier, traits); ``` -Here we are setting the trait key `app_version` with the value of `YourApplication.getVersion()`.You can now create a [Segment](segments.md) that is based on the application version and manage features based on the application version. +Here we are setting the trait key `app_version` with the value of `YourApplication.getVersion()`.You can now create a [Segment](./segments) that is based on the application version and manage features based on the application version. Traits are completely free-form. You can store any number of traits, with any relevant information you see fit, in the platform and then use Segments to control features based on these Trait values. diff --git a/docs/docs/flagsmith-concepts/segments/index.md b/docs/docs/flagsmith-concepts/segments/index.md index 6a7967f85db7..5c8cfd7c9d49 100644 --- a/docs/docs/flagsmith-concepts/segments/index.md +++ b/docs/docs/flagsmith-concepts/segments/index.md @@ -7,9 +7,9 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Segments -A segment is a subset of [identities](/basic-features/managing-identities.md), defined by a set of rules that match identity [traits](managing-identities.md#identity-traits). An identity always belongs to a single environment and can belong to any number of segments. +A segment is a subset of [identities](../identities), defined by a set of rules that match identity [traits](../identities#identity-traits). An identity always belongs to a single environment and can belong to any number of segments. -Once you have defined a segment, you can create **segment overrides** for features within an environment. A segment override allows you to control the state of a feature only for identities that belong to a specific segment. This is similar to how [identity overrides](managing-identities.md#identity-overrides) let you control the state of features for an explicit set of identities that is known in advance. +Once you have defined a segment, you can create **segment overrides** for features within an environment. A segment override allows you to control the state of a feature only for identities that belong to a specific segment. This is similar to how [identity overrides](../identities#identity-overrides) let you control the state of features for an explicit set of identities that is known in advance. Because segments are driven by identity traits, your application must identify the user when retrieving flags in order for segment overrides to be applied. If your user is not identified, no overrides will be applied and all flags will be returned exactly as they are defined in the current environment. @@ -17,7 +17,7 @@ Segments and segment overrides can be used to implement many scenarios. For exam - Test features in production before they are released by overriding them only for internal users or a QA team - Deliver features only to "power users" who have logged in a certain number of times, have used specific functionality within your application, or any combination of factors -- Force a group of users into a specific [A/B test](advanced-use/ab-testing.md) variation by overriding weightings on [multivariate flags](managing-features.md#multi-variate-flags) +- Force a group of users into a specific [A/B test](advanced-use/ab-testing.md) variation by overriding weightings on [multivariate flags](../../basic-features/managing-features.md#multi-variate-flags) - Override behaviour based on the [application version number](/guides-and-examples/mobile-app-versioning.md), e.g. by using the SemVer rule operators - Control features based on the time of day, date, weekday, etc. by passing it as a trait when evaluating flags for an identity @@ -108,4 +108,4 @@ The following string trait values will evaluate to `true`: ## What's next - Learn more about [segment rule operators](./segment-rule-operators.md) -- Learn about [targeting and rollouts](/flagsmith-concepts/targeting-and-rollouts.md) +- Learn about [targeting and rollouts](../targeting-and-rollouts) From 4d10a4451a9e44f00242d91cb831ee7b8efee4a7 Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Thu, 31 Jul 2025 14:33:40 -0300 Subject: [PATCH 09/12] doc: adjust capitalisation --- docs/docs/flagsmith-concepts/data-model.md | 8 ++-- docs/docs/flagsmith-concepts/identities.md | 46 +++++++++---------- .../platform-architecture.md | 2 +- .../docs/flagsmith-concepts/segments/index.md | 4 +- .../segments/segment-rule-operators.md | 4 +- 5 files changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/docs/flagsmith-concepts/data-model.md b/docs/docs/flagsmith-concepts/data-model.md index 6dc75d46b22f..5d129b859d3c 100644 --- a/docs/docs/flagsmith-concepts/data-model.md +++ b/docs/docs/flagsmith-concepts/data-model.md @@ -16,21 +16,21 @@ OK let's break this down. Organisations allow you and other team members to manage projects and their features. A user can be a member of multiple organisations. ### Projects -Projects contain one or more Environments that share a single set of Features. Organisations can have any number of Projects. +Projects contain one or more environments that share a single set of features. Organisations can have any number of projects. ### Environments Environments are a way to separate the configuration of your features. For example, a feature might be enabled in your project's Development and Staging environments but turned off in your Production environment. A project can have any number of environments. ### Features -Features are shared across all Environments within a Project, but their values/states can be modified per Environment. Features can be toggled on/off or assigned values (e.g., string, integer, boolean, or multivariate values). +Features are shared across all environments within a project, but their values/states can be modified per environment. Features can be toggled on/off or assigned values (e.g., string, integer, boolean, or multivariate values). ### Identities -Identities are a particular user registration for one of your Project's Environments. Registering identities within the client application allows you to manage features for individual users. Identity features can be overridden from your environment defaults. For example, joe@yourwebsite.com would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment. +Identities are a particular user registration for one of your project's environments. Registering identities within the client application allows you to manage features for individual users. Identity features can be overridden from your environment defaults. For example, joe@yourwebsite.com would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment. For more information, see [Identities](/basic-features/managing-identities). ### Traits -You can store any number of Traits against an Identity. Traits are key-value pairs that can store any type of data. Some examples of traits that you might store against an Identity include: +You can store any number of traits against an identity. Traits are key-value pairs that can store any type of data. Some examples of traits that you might store against an identity include: - The number of times the user has logged in. - Whether they have accepted the application terms and conditions. - Their preferred application theme. diff --git a/docs/docs/flagsmith-concepts/identities.md b/docs/docs/flagsmith-concepts/identities.md index 355b3b76877c..9468b834d601 100644 --- a/docs/docs/flagsmith-concepts/identities.md +++ b/docs/docs/flagsmith-concepts/identities.md @@ -4,42 +4,42 @@ sidebar_label: Identities sidebar_position: 30 --- -Feature flags are great, but they can be a very blunt tool, only allowing you to enable or disable flags across your entire user base. In order to target users more precisely, and to be able to perform [staged feature roll-outs](/guides-and-examples/staged-feature-rollouts.md) or [A/B and multivariate tests](/advanced-use/ab-testing.md), you need to _Identify your Users_. +Feature flags are great, but they can be a very blunt tool, only allowing you to enable or disable flags across your entire user base. In order to target users more precisely, and to be able to perform [staged feature roll-outs](/guides-and-examples/staged-feature-rollouts.md) or [A/B and multivariate tests](/advanced-use/ab-testing.md), you need to _identify your users_. -Identities are created within Flagsmith automatically the first time they are identified from your client SDKs. Generally, you would make a call to identify a user with a unique string or identifier whenever they log into your application or site. The SDK will then send an API message to the Flagsmith API, with the relevant Identity information. +Identities are created within Flagsmith automatically the first time they are identified from your client SDKs. Generally, you would make a call to identify a user with a unique string or identifier whenever they log into your application or site. The SDK will then send an API message to the Flagsmith API, with the relevant identity information. :::tip -The SDK part of the Flagsmith API is public by design; the Environment Key is intended to be public. When identifying users, it is important to use an Identity value that is not easy to guess. For example, if you used an incrementing integer to identify your users, it would be trivial to request Identities by enumerating this integer. This would effectively provide public access to any user traits that are associated with users. +The SDK part of the Flagsmith API is public by design; the environment key is intended to be public. When identifying users, it is important to use an identity value that is not easy to guess. For example, if you used an incrementing integer to identify your users, it would be trivial to request identities by enumerating this integer. This would effectively provide public access to any user traits that are associated with users. -We strongly recommend using an unguessable, unidentifiable Identity Key, such as a [GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), when identifying your users, to prevent unintentionally leaking Identity trait data. +We strongly recommend using an unguessable, unidentifiable identity key, such as a [GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), when identifying your users, to prevent unintentionally leaking identity trait data. ::: ## Identity Overrides -Once you have uniquely identified a user, you can then override features for that user from your Environment defaults. For example, you've pushed a feature into production, but the relevant feature flag is still hiding that feature from all of your users. You can now override that flag for your own user, and test that feature. Once you are happy with everything, you can roll that feature out to all of your users by enabling the flag itself. +Once you have uniquely identified a user, you can then override features for that user from your environment defaults. For example, you've pushed a feature into production, but the relevant feature flag is still hiding that feature from all of your users. You can now override that flag for your own user, and test that feature. Once you are happy with everything, you can roll that feature out to all of your users by enabling the flag itself. -Identities are specific and individual for each Environment within your project. For example, joe@yourwebsite.com would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment. +Identities are specific and individual for each environment within your project. For example, joe@yourwebsite.com would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment. ## Identity Feature Flags -By default, Identities receive the default flags for their environment. The main use-case for identities is to be able to override flags and configs on a per-identity basis. You can do this by navigating to the Users page, finding the User -and modifying their Flags. +By default, identities receive the default flags for their environment. The main use-case for identities is to be able to override flags and configs on a per-identity basis. You can do this by navigating to the users page, finding the user +and modifying their flags. ## Identity Traits -You can also use Flagsmith to store 'Traits' against identities. Traits are key/value pairs that are associated with individual Identities for a particular Environment. Traits have two purposes outlined below, but the main use case is to drive [Segments](./segments). +You can also use Flagsmith to store 'traits' against identities. traits are key/value pairs that are associated with individual identities for a particular environment. traits have two purposes outlined below, but the main use case is to drive [segments](./segments). :::important -The maximum size of each individual Trait Value is **_2000 bytes_**. You cannot store more data than that in a single trait, and the API will return a 500 error if you try to do so. +The maximum size of each individual trait value is **_2000 bytes_**. You cannot store more data than that in a single trait, and the API will return a 500 error if you try to do so. ::: -### Using Traits to drive Segments +### Using Traits to Drive Segments -Let's say you are working on a mobile app, and you want to control a feature based on the version of the application that the Identity is using. When you integrate the Flagsmith SDK, you would pass the application version number to the Flagsmith platform as a trait key/value pair: +Let's say you are working on a mobile app, and you want to control a feature based on the version of the application that the identity is using. When you integrate the Flagsmith SDK, you would pass the application version number to the Flagsmith platform as a trait key/value pair: ```java String identifier = "user_512356" @@ -49,17 +49,17 @@ traits.put("app_version", YourApplication.getVersion()); Flags flags = flagsmith.getIdentityFlags(identifier, traits); ``` -Here we are setting the trait key `app_version` with the value of `YourApplication.getVersion()`.You can now create a [Segment](./segments) that is based on the application version and manage features based on the application version. +Here we are setting the trait key `app_version` with the value of `YourApplication.getVersion()`.You can now create a [segment](./segments) that is based on the application version and manage features based on the application version. -Traits are completely free-form. You can store any number of traits, with any relevant information you see fit, in the platform and then use Segments to control features based on these Trait values. +Traits are completely free-form. You can store any number of traits, with any relevant information you see fit, in the platform and then use segments to control features based on these trait values. ## Identity and Trait Storage -Identities are persisted within the Flagsmith platform, along with any Traits that have been assigned to them. When Flags are evaluated for an Identity, the full complement of Traits stored within the platform are used, even if they were not all sent as part of the request. +Identities are persisted within the Flagsmith platform, along with any traits that have been assigned to them. When flags are evaluated for an identity, the full complement of traits stored within the platform are used, even if they were not all sent as part of the request. -This can be useful if, at runtime, your application does not have all the relevant Trait data available for that particular Identity; any Traits provided will be combined with the Traits stored within Flagsmith before the evaluation engine runs. +This can be useful if, at runtime, your application does not have all the relevant trait data available for that particular identity; any traits provided will be combined with the traits stored within Flagsmith before the evaluation engine runs. -There are some [exceptions to this rule](/clients#server-side-sdks) with Server Side SDKs running in local evaluation mode. +There are some [exceptions to this rule](/clients#server-side-sdks) with Server-side SDKs running in local evaluation mode. :::info @@ -67,7 +67,7 @@ Note that, when using our SaaS platform, there might be a short delay from the i ::: -### Using Traits as a data-store +### Using Traits as a Data-store Traits can also be used to store additional data about your users that would be cumbersome to store within your application. Some possible uses for traits could be: @@ -78,9 +78,9 @@ Generally if they are lower-value pieces of information about your user, it migh Traits are stored natively as either numbers, strings or booleans. -## Traits powering Segments +## Traits Powering Segments -Traits can be used within your application, but they can also be used to power [Segments](/basic-features/segments.md). +Traits can be used within your application, but they can also be used to power [segments](/basic-features/segments.md). ## Trait Value Data Types @@ -97,13 +97,13 @@ Trait values can be stored as one of four different data types: - Int (32 bit signed) - Float (typically has a range of around 1E-307 to 1E+308 with a precision of at least 15 digits) -If you need to store 64 bit integers or very high precision floats we suggest storing them as Strings and then doing the type conversion within the SDK. +If you need to store 64 bit integers or very high precision floats we suggest storing them as strings and then doing the type conversion within the SDK. ## Bulk Uploading Identities and Traits -Identities are lazily created within Flagsmith. There might be instances where you want to push Identity and Trait data into the platform outside of a user session. We have a [code example for this](/clients/rest#bulk-uploading-identities-and-traits). +Identities are lazily created within Flagsmith. There might be instances where you want to push identity and trait data into the platform outside of a user session. We have a [code example for this](/clients/rest#bulk-uploading-identities-and-traits). For more information, see: -- [Managing Identities](/basic-features/managing-identities) +- [Managing identities](/basic-features/managing-identities) diff --git a/docs/docs/flagsmith-concepts/platform-architecture.md b/docs/docs/flagsmith-concepts/platform-architecture.md index 14a3bce0f290..bdd33c905466 100644 --- a/docs/docs/flagsmith-concepts/platform-architecture.md +++ b/docs/docs/flagsmith-concepts/platform-architecture.md @@ -12,7 +12,7 @@ Flagsmith architecture supports a range of deployment models to suit different o The most important components in Flagsmith's architecture are: -- **Frontend Dashboard**: A web interface for managing projects, environments, feature flags, and user permissions. This is where most configuration and management tasks are performed. +- **Frontend dashboard**: A web interface for managing projects, environments, feature flags, and user permissions. This is where most configuration and management tasks are performed. - **Core API**: RESTful API that powers the dashboard and SDKs. These endpoints are used for automation, integrations, and direct management of Flagsmith resources. - **Edge API**: A globally distributed API for low-latency flag evaluation, especially useful for applications with users around the world. - **SDKs**: Client libraries (available for many languages and platforms) that connect your applications and services to Flagsmith, enabling real-time feature flag evaluation and remote configuration. diff --git a/docs/docs/flagsmith-concepts/segments/index.md b/docs/docs/flagsmith-concepts/segments/index.md index 5c8cfd7c9d49..f58b6277a0ed 100644 --- a/docs/docs/flagsmith-concepts/segments/index.md +++ b/docs/docs/flagsmith-concepts/segments/index.md @@ -31,9 +31,9 @@ Segment definitions _are_ served to clients running in [local evaluation mode](/ ## Creating project or feature-specific segments -Segments created from the Segments page of the Flagsmith dashboard can be used to override any feature within a single project. +Segments created from the segments page of the Flagsmith dashboard can be used to override any feature within a single project. -To create a segment override, click on a feature in a specific environment and go to the Segment Overrides tab. +To create a segment override, click on a feature in a specific environment and go to the segment overrides tab. If you need to create a segment that will only ever be used to override a single feature, you can create a **feature-specific segment** by clicking on "Create Feature-Specific Segment" when creating a segment override. Feature-specific segments are otherwise functionally identical to project segments. By default, feature-specific segments are not shown in the Segments page, unless you enable the "Include Feature-Specific" option. diff --git a/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md b/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md index 8201da859999..0e4ce8eb072d 100644 --- a/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md +++ b/docs/docs/flagsmith-concepts/segments/segment-rule-operators.md @@ -55,9 +55,9 @@ Percentage Split is the only operator that does not require a trait. You can use Percentage Split deterministically assigns a "bucket" to each identity solely based on its ID and not any traits, meaning that Segment overrides that use Percentage Split will always result in the same feature value for a given identity. -If you create a Segment with a single Percentage Split rule, Identities who are members of that split when the split value is set to, say, 10% will be guaranteed to also be in that split if it is changed to a value higher than 10%. +If you create a segment with a single percentage split rule, identities who are members of that split when the split value is set to, say, 10% will be guaranteed to also be in that split if it is changed to a value higher than 10%. -If the Percentage Split is reduced in value, some Identities will be removed from that Percentage Split to maintain the balance. The algorithm is fairly simple and good to understand – it is [described here](/guides-and-examples/staged-feature-rollouts#how-does-it-work). +If the percentage split is reduced in value, some identities will be removed from that percentage split to maintain the balance. The algorithm is fairly simple and good to understand – it is [described here](/guides-and-examples/staged-feature-rollouts#how-does-it-work). From 33131a1695ed93463fb2f73e13747a9ed5d57b15 Mon Sep 17 00:00:00 2001 From: Guilherme Date: Fri, 1 Aug 2025 10:52:01 -0300 Subject: [PATCH 10/12] Apply suggestions from code review Co-authored-by: Robert Norrie --- docs/docs/flagsmith-concepts/data-model.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/flagsmith-concepts/data-model.md b/docs/docs/flagsmith-concepts/data-model.md index 5d129b859d3c..29c6935e31aa 100644 --- a/docs/docs/flagsmith-concepts/data-model.md +++ b/docs/docs/flagsmith-concepts/data-model.md @@ -6,7 +6,7 @@ sidebar_position: 10 Flagsmith uses a flexible data model to help you manage feature flags and remote configurations across multiple projects, environments, and user groups. -Here's a high-level overview of the Flagsmith data model. Fear not - it's not as complex as it looks! +Here's a high-level overview of the Flagsmith data model. ![Image](/img/flagsmith-model.svg) @@ -33,7 +33,7 @@ For more information, see [Identities](/basic-features/managing-identities). You can store any number of traits against an identity. Traits are key-value pairs that can store any type of data. Some examples of traits that you might store against an identity include: - The number of times the user has logged in. - Whether they have accepted the application terms and conditions. -- Their preferred application theme. +Their theme preference (eg. dark mode) - Whether they have performed certain actions within your application. For more information, see [Traits](/basic-features/managing-identities.md#identity-traits). From 6fb2689a42d0c72ec98a74766953830be503a125 Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Fri, 8 Aug 2025 08:05:42 -0300 Subject: [PATCH 11/12] doc: add header on data model --- docs/docs/flagsmith-concepts/data-model.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docs/flagsmith-concepts/data-model.md b/docs/docs/flagsmith-concepts/data-model.md index 29c6935e31aa..b8cb818a176e 100644 --- a/docs/docs/flagsmith-concepts/data-model.md +++ b/docs/docs/flagsmith-concepts/data-model.md @@ -10,7 +10,8 @@ Here's a high-level overview of the Flagsmith data model. ![Image](/img/flagsmith-model.svg) -OK let's break this down. +## Key Concepts +Below you'll find a quick explanation of the main building blocks that make up the Flagsmith data model. ### Organisations Organisations allow you and other team members to manage projects and their features. A user can be a member of multiple organisations. From daedcc875bd91ece6702b8bac1ca5d05ac0d646b Mon Sep 17 00:00:00 2001 From: Guilherme Afonso Date: Fri, 8 Aug 2025 08:08:41 -0300 Subject: [PATCH 12/12] doc: small adjustment on phrasing --- docs/docs/flagsmith-concepts/data-model.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/docs/flagsmith-concepts/data-model.md b/docs/docs/flagsmith-concepts/data-model.md index b8cb818a176e..fa159bd3d5c0 100644 --- a/docs/docs/flagsmith-concepts/data-model.md +++ b/docs/docs/flagsmith-concepts/data-model.md @@ -11,26 +11,33 @@ Here's a high-level overview of the Flagsmith data model. ![Image](/img/flagsmith-model.svg) ## Key Concepts + Below you'll find a quick explanation of the main building blocks that make up the Flagsmith data model. ### Organisations + Organisations allow you and other team members to manage projects and their features. A user can be a member of multiple organisations. ### Projects + Projects contain one or more environments that share a single set of features. Organisations can have any number of projects. ### Environments + Environments are a way to separate the configuration of your features. For example, a feature might be enabled in your project's Development and Staging environments but turned off in your Production environment. A project can have any number of environments. ### Features + Features are shared across all environments within a project, but their values/states can be modified per environment. Features can be toggled on/off or assigned values (e.g., string, integer, boolean, or multivariate values). ### Identities -Identities are a particular user registration for one of your project's environments. Registering identities within the client application allows you to manage features for individual users. Identity features can be overridden from your environment defaults. For example, joe@yourwebsite.com would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment. + +Identities are individual users associated with each environment. Registering identities within the client application allows you to manage features for individual users. Identity features can be overridden from your environment defaults. For example, joe@yourwebsite.com would be a different identity in your development environment to the one in production, and they can have different features enabled for each environment. For more information, see [Identities](/basic-features/managing-identities). ### Traits + You can store any number of traits against an identity. Traits are key-value pairs that can store any type of data. Some examples of traits that you might store against an identity include: - The number of times the user has logged in. - Whether they have accepted the application terms and conditions. @@ -40,6 +47,7 @@ Their theme preference (eg. dark mode) For more information, see [Traits](/basic-features/managing-identities.md#identity-traits). ### Segments + Segments define a group of users by traits such as login count, device, location, or any number of custom-defined traits. Similar to individual users, you can override environment defaults for features for a segment. For example, you might show certain features for a "power user" segment. For more information, see [Segments](/basic-features/segments.md).