mirror of
https://github.com/Unleash/unleash.git
synced 2025-01-25 00:07:47 +01:00
This is first iteration for docs.
This commit is contained in:
Jaanus Sellin
GitHub
parent
242f31c251
commit
d2176880e2
@ -11,34 +11,34 @@ This document attempts to guide developers in implementing an Unleash Client SDK
|
||||
|
||||
Unleash is composed of three parts:
|
||||
|
||||
- **Unleash API** - The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
|
||||
- **Unleash UI** - The dashboard used to manage feature toggles, define new strategies, look at metrics, etc.
|
||||
- **Unleash API** - The service holding all feature flags and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
|
||||
- **Unleash UI** - The dashboard used to manage feature flags, define new strategies, look at metrics, etc.
|
||||
- **Unleash SDK** - Used by clients to check if a feature is enabled or disabled. The SDK also collects metrics and sends them to the Unleash API. Activation Strategies are also implemented in the SDK. Unleash currently provides official SDKs for Java and Node.js
|
||||
|
||||
|
||||
|
||||
To be super fast, the client SDK caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database.
|
||||
To be super fast, the client SDK caches all feature flags and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a flag is on or off because it is just a simple function operating on local state, without the need to poll data from the database.
|
||||
|
||||
## The Basics {#the-basics}
|
||||
|
||||
All client implementations should strive to have a consistent and straightforward user API. It should be a simple method, called isEnabled, to check if a feature toggle is enabled or not. The method should return a `boolean` value, true or false.
|
||||
All client implementations should strive to have a consistent and straightforward user API. It should be a simple method, called isEnabled, to check if a feature flag is enabled or not. The method should return a `boolean` value, true or false.
|
||||
|
||||
```javascript
|
||||
unleash.isEnabled('myAwesomeToggle');
|
||||
unleash.isEnabled('myAwesomeFlag');
|
||||
```
|
||||
|
||||
The basic `isEnabled` method should also accept a default value. This should be used if the client does not know anything about a particular toggle. If the user does not specify a default value, false should be returned for unknown feature toggles.
|
||||
The basic `isEnabled` method should also accept a default value. This should be used if the client does not know anything about a particular flag. If the user does not specify a default value, false should be returned for unknown feature flags.
|
||||
|
||||
**Calling unleash with default value:**
|
||||
|
||||
```javascript
|
||||
boolean value = unleash.isEnabled("unknownFeatureToggle", false);
|
||||
boolean value = unleash.isEnabled("unknownFeatureFlag", false);
|
||||
//value==false because default value was used.
|
||||
```
|
||||
|
||||
### Implementation of isEnabled {#implementation-of-isenabled}
|
||||
|
||||
A feature toggle is defined as:
|
||||
A feature flag is defined as:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -70,18 +70,18 @@ A simple demo of the `isEnabled` function in JavaScript style (most of the imple
|
||||
|
||||
```javascript
|
||||
function isEnabled(name, unleashContext = {}, defaultValue = false) {
|
||||
const toggle = toggleRepository.get(name);
|
||||
const flag = toggleRepository.get(name);
|
||||
let enabled = false;
|
||||
|
||||
if (!toggle) {
|
||||
if (!flag) {
|
||||
return defaultValue;
|
||||
} else if (!toggle.isEnabled) {
|
||||
} else if (!flag.isEnabled) {
|
||||
return false;
|
||||
} else {
|
||||
for (let i = 0; i < toggle.strategies.length; i++) {
|
||||
let strategyDef = toggle.strategies[i];
|
||||
for (let i = 0; i < flag.strategies.length; i++) {
|
||||
let strategyDef = flag.strategies[i];
|
||||
let strategyImpl = strategyImplRepository.get(strategyDef.name);
|
||||
if (strategyImpl.isEnabled(toggle.parameters, unleashContext)) {
|
||||
if (strategyImpl.isEnabled(flag.parameters, unleashContext)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
@ -100,9 +100,9 @@ Unleash also ships with a few built-in strategies, and expects client SDK's to i
|
||||
|
||||
Client implementation should also provide a defined interface to make it easier for the user to implement their own activation strategies, and register those in the Unleash client.
|
||||
|
||||
## Fetching feature toggles (polling) {#fetching-feature-toggles-polling}
|
||||
## Fetching feature flags (polling) {#fetching-feature-toggles-polling}
|
||||
|
||||
The client implementation should fetch toggles in the background as regular polling. In a thread-based environment, such as Java, this needs to be done in a separate thread. The default poll interval should be **15 seconds**, and it should also be configurable.
|
||||
The client implementation should fetch flags in the background as regular polling. In a thread-based environment, such as Java, this needs to be done in a separate thread. The default poll interval should be **15 seconds**, and it should also be configurable.
|
||||
|
||||
## Client registration {#client-registration}
|
||||
|
||||
@ -110,8 +110,8 @@ On start-up, the clients should register with the Unleash server. The registrati
|
||||
|
||||
## Metrics {#metrics}
|
||||
|
||||
Clients are expected to send metrics back to Unleash API at regular intervals. The metrics are a list of used toggles and how many times they evaluated to yes or no in at the time of requesting the metrics. Read more about how to send metrics in the [Metrics API](/reference/api/legacy/unleash/client/metrics.md) documentation.
|
||||
Clients are expected to send metrics back to Unleash API at regular intervals. The metrics are a list of used flags and how many times they evaluated to yes or no in at the time of requesting the metrics. Read more about how to send metrics in the [Metrics API](/reference/api/legacy/unleash/client/metrics.md) documentation.
|
||||
|
||||
## Backup Feature Toggles {#backup-feature-toggles}
|
||||
## Backup Feature Flags {#backup-feature-toggles}
|
||||
|
||||
The SDK also persists the latest known state to a local file on the instance where the client is running. It will store a local copy every time the client receives changes from the API. Having a local backup of the latest known state minimises the consequences of clients not being able to talk to the Unleash API on startup. This is necessary due to network unreliability.
|
||||
|
||||
@ -8,7 +8,7 @@ import VideoContent from '@site/src/components/VideoContent.jsx'
|
||||
Placeholders in the code samples below are delimited by angle brackets (i.e. `<placeholder-name>`). You will need to replace them with the values that are correct in _your_ situation for the code samples to run properly.
|
||||
:::
|
||||
|
||||
Unleash allows you to gather [**impression data**](../reference/impression-data.md) from your feature toggles, giving you complete visibility into who checked what toggles and when. What you do with this data is entirely up to you, but a common use case is to send it off to an aggregation and analytics service such as [Posthog](https://posthog.com/) or [Google Analytics](https://analytics.google.com/), either just for monitoring purposes or to facilitate [A/B testing](../topics/a-b-testing.md).
|
||||
Unleash allows you to gather [**impression data**](../reference/impression-data.md) from your feature flags, giving you complete visibility into who checked what flags and when. What you do with this data is entirely up to you, but a common use case is to send it off to an aggregation and analytics service such as [Posthog](https://posthog.com/) or [Google Analytics](https://analytics.google.com/), either just for monitoring purposes or to facilitate [A/B testing](../topics/a-b-testing.md).
|
||||
|
||||
This guide will take you through everything you need to do in Unleash to facilitate such a workflow. It will show you how to send data to Posthog as an example sink, but the exact same principles will apply to any other service of the same kind.
|
||||
|
||||
@ -21,33 +21,33 @@ We will assume that you have the necessary details for your third-party service:
|
||||
- **where to send the data to**. We'll refer to this in the code samples below as **`<sink-url>`**.
|
||||
- **what format the data needs to be in**. This will determine how you transform the event data before you send it.
|
||||
|
||||
In addition, you'll need to have a toggle to record impression data for and an [Unleash client SDK](../reference/sdks/index.md) that supports impression data. This guide will use the [JavaScript proxy SDK](/docs/generated/sdks/client-side/javascript-browser.md).
|
||||
In addition, you'll need to have a flag to record impression data for and an [Unleash client SDK](../reference/sdks/index.md) that supports impression data. This guide will use the [JavaScript proxy SDK](/docs/generated/sdks/client-side/javascript-browser.md).
|
||||
|
||||
When you have those things sorted, follow the below steps.
|
||||
|
||||
## Step 1: Enable impression data for your feature toggle {#step-1}
|
||||
## Step 1: Enable impression data for your feature flag {#step-1}
|
||||
|
||||
Because impression data is an **opt-in feature**, the first step is to enable it for the feature you want to gather data from. You can use both the UI and the API.
|
||||
|
||||
### Enabling impression data for new feature toggles {#step-1-new-toggles}
|
||||
### Enabling impression data for new feature flags {#step-1-new-toggles}
|
||||
|
||||
When you create a new feature toggle via the UI, there's an option at the end of the form that you must enable:
|
||||
When you create a new feature flag via the UI, there's an option at the end of the form that you must enable:
|
||||
|
||||
|
||||
|
||||
|
||||
To create a feature toggle with impression data enabled, set the `impressionData` option to `true` in the request payload, as seen below. For more options, check the [reference docs on creating features](/reference/api/legacy/unleash/admin/features-v2.md#create-toggle).
|
||||
To create a feature flag with impression data enabled, set the `impressionData` option to `true` in the request payload, as seen below. For more options, check the [reference docs on creating features](/reference/api/legacy/unleash/admin/features-v2.md#create-toggle).
|
||||
|
||||
<ApiRequest verb="post" payload={{name: "<feature-toggle-name>", impressionData: true}} url="api/admin/projects/<project-id>/features" title="Create a feature toggle with impression data enabled."/>
|
||||
<ApiRequest verb="post" payload={{name: "<feature-flag-name>", impressionData: true}} url="api/admin/projects/<project-id>/features" title="Create a feature flag with impression data enabled."/>
|
||||
|
||||
### Enabling impression data for existing feature toggles {#step-1-existing-toggles}
|
||||
### Enabling impression data for existing feature flags {#step-1-existing-toggles}
|
||||
|
||||
To enable impression data for an existing toggle, go to the "Settings" tab of that feature toggle and use the "edit" button near the Feature information title in the admin UI. It will take you to a form that looks like the toggle creation form. Use the "Enable impression data" toggle to enable it, the same way you would when [enabling impression data for a new feature toggle](#step-1-new-toggles).
|
||||
To enable impression data for an existing flag, go to the "Settings" tab of that feature flag and use the "edit" button near the Feature information title in the admin UI. It will take you to a form that looks like the flag creation form. Use the "Enable impression data" flag to enable it, the same way you would when [enabling impression data for a new feature flag](#step-1-new-toggles).
|
||||
|
||||
|
||||
|
||||
|
||||
To enable impression data for an existing toggle, use the [API's toggle patching functionality](/reference/api/legacy/unleash/admin/features-v2.md#patch-toggle):
|
||||
To enable impression data for an existing flag, use the [API's flag patching functionality](/reference/api/legacy/unleash/admin/features-v2.md#patch-toggle):
|
||||
|
||||
<ApiRequest verb="patch" payload={[{op: "replace", path: "/impressionData", value: true}]} url="api/admin/projects/<project-id>/features/<feature-toggle-name>" title="Enable impression data on an existing toggle."/>
|
||||
<ApiRequest verb="patch" payload={[{op: "replace", path: "/impressionData", value: true}]} url="api/admin/projects/<project-id>/features/<feature-flag-name>" title="Enable impression data on an existing flag."/>
|
||||
|
||||
|
||||
## Step 2: Capture impression events in your client {#step-2}
|
||||
@ -83,5 +83,5 @@ unleash.on("impression", (event) => {
|
||||
```
|
||||
|
||||
Posthog expects an object with a `distinct_id` property that it uses to correlate data.
|
||||
Additionally, you can add whatever properties you want, such as the feature toggle name, its state and/or variant, or the whole Unleash context.
|
||||
Additionally, you can add whatever properties you want, such as the feature flag name, its state and/or variant, or the whole Unleash context.
|
||||
The `posthog.capture` method sends the event data to your Posthog instance.
|
||||
|
||||
@ -44,7 +44,7 @@ Importantly, while references to [segments](/reference/segments.mdx) are exporte
|
||||
|
||||
You can export features either from a project search or the global feature search. Use the search functionality to narrow the results to the list of features you want to export and use the export button to select environment. All features included in your search results will be included in the export.
|
||||
|
||||
<Figure caption='Feature toggle lists can be filtered using the search bar. Once filtered, you can use the "export current selection" button to export the configuration for those features.' img="/img/export.png"/>
|
||||
<Figure caption='Feature flag lists can be filtered using the search bar. Once filtered, you can use the "export current selection" button to export the configuration for those features.' img="/img/export.png"/>
|
||||
|
||||
## Import
|
||||
|
||||
@ -112,9 +112,9 @@ Unleash will verify that any custom strategies you are trying to import have alr
|
||||
|
||||
### Required permissions
|
||||
|
||||
To import features, you will **always** require the **update feature toggles** permission.
|
||||
To import features, you will **always** require the **update feature flags** permission.
|
||||
Additionally, depending on the actions your import job would trigger, you may also require any of the following permissions:
|
||||
* **Create feature toggles**: when the import would create new features
|
||||
* **Create feature flags**: when the import would create new features
|
||||
* **Update tag types**: when the import would create new tag types
|
||||
* **Create context fields**: when the import would create new context fields
|
||||
* **Create activation strategies**: when the import would add activation strategies to a feature and change requests are disabled
|
||||
@ -132,7 +132,7 @@ If change requests are enabled, any permissions for **Create activation strategi
|
||||
|
||||
Environment import/export has some similarities to the [instance import/export API](how-to-import-export.md), but they serve different purposes.
|
||||
|
||||
The instance import/export API was designed to export all feature toggles (optionally with strategies and projects) from one Unleash instance to another. When it was developed, Unleash had much fewer features than it does now. As such, the API lacks support for some of the more recent features in Unleash.
|
||||
The instance import/export API was designed to export all feature flags (optionally with strategies and projects) from one Unleash instance to another. When it was developed, Unleash had much fewer features than it does now. As such, the API lacks support for some of the more recent features in Unleash.
|
||||
|
||||
On the other hand, the environment import/export feature was designed to export a selection of features based on search criteria. It can only export data from a single environment and only import it to a single environment. It also only supports importing into a single project (although it can export features from multiple projects).
|
||||
|
||||
|
||||
@ -8,16 +8,16 @@ In order to access the admin API endpoints you need to identify yourself. Unless
|
||||
:::
|
||||
|
||||
|
||||
## Fetching Feature Toggles {#fetching-feature-toggles}
|
||||
## Fetching Feature Flags {#fetching-feature-toggles}
|
||||
|
||||
|
||||
**Available since Unleash v4.3**
|
||||
|
||||
In this document we will guide you on how you can work with feature toggles and their configuration. Please remember the following details:
|
||||
In this document we will guide you on how you can work with feature flags and their configuration. Please remember the following details:
|
||||
|
||||
- All feature toggles exists _inside a project_.
|
||||
- A feature toggle exists _across all environments_.
|
||||
- A feature toggle can take different configuration, activation strategies, per environment.
|
||||
- All feature flags exists _inside a project_.
|
||||
- A feature flag exists _across all environments_.
|
||||
- A feature flag can take different configuration, activation strategies, per environment.
|
||||
|
||||
|
||||
:::note
|
||||
@ -29,7 +29,7 @@ This document lists HTTP request data and [cURL](https://curl.se/) and [HTTPie](
|
||||
|
||||
<ApiRequest verb="get" url="api/admin/projects/:project-id" title="Get a project overview"/>
|
||||
|
||||
This endpoint will give you an general overview of a project. It will return essential details about a project, in addition it will return all feature toggles and high level environment details per feature toggle.
|
||||
This endpoint will give you an general overview of a project. It will return essential details about a project, in addition it will return all feature flags and high level environment details per feature flag.
|
||||
|
||||
**Example Query**
|
||||
|
||||
@ -91,15 +91,15 @@ http GET http://localhost:4242/api/admin/projects/default Authorization:$KEY
|
||||
}
|
||||
```
|
||||
|
||||
From the results we can see that we have received two feature toggles, _demo_, _demo.test_, and other useful metadata about the project.
|
||||
From the results we can see that we have received two feature flags, _demo_, _demo.test_, and other useful metadata about the project.
|
||||
|
||||
|
||||
### Get All Feature Toggles {#fetching-toggles}
|
||||
### Get All Feature Flags {#fetching-toggles}
|
||||
|
||||
|
||||
<ApiRequest verb="get" url="api/admin/projects/:projectId/features" title="Get all feature toggles in a project"/>
|
||||
<ApiRequest verb="get" url="api/admin/projects/:projectId/features" title="Get all feature flags in a project"/>
|
||||
|
||||
This endpoint will return all feature toggles and high level environment details per feature toggle for a given _projectId_
|
||||
This endpoint will return all feature flags and high level environment details per feature flag for a given _projectId_
|
||||
|
||||
**Example Query**
|
||||
|
||||
@ -157,28 +157,28 @@ Authorization:$KEY
|
||||
"version": 1
|
||||
}
|
||||
```
|
||||
### Create Feature Toggle {#create-toggle}
|
||||
### Create Feature Flag {#create-toggle}
|
||||
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features" title="Create a feature toggle with the specified details (example data)" payload={{ name: "my-feature-toggle" }}/>
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features" title="Create a feature flag with the specified details (example data)" payload={{ name: "my-feature-flag" }}/>
|
||||
|
||||
This endpoint will accept HTTP POST request to create a new feature toggle for a given _projectId_
|
||||
This endpoint will accept HTTP POST request to create a new feature flag for a given _projectId_
|
||||
|
||||
**Toggle options**
|
||||
**Flag options**
|
||||
|
||||
This endpoint accepts the following toggle options:
|
||||
This endpoint accepts the following flag options:
|
||||
|
||||
| Property name | Required | Description | Example value |
|
||||
|------------------|----------|--------------------------------------------------------------------------------------------------------------|-------------------------|
|
||||
| `name` | Yes | The name of the feature toggle. | `"my-feature-toggle"` |
|
||||
| `description` | No | The feature toggle's description. Defaults to an empty string. | `"Turn my feature on!"` |
|
||||
| `impressionData` | No | Whether to enable [impression data](/reference/impression-data.md) for this toggle. Defaults to `false.` | `true` |
|
||||
| `type` | No | The [type of toggle](/reference/feature-toggle-types.md) you want to create. Defaults to `"release"` | `"release"` |
|
||||
| `name` | Yes | The name of the feature flag. | `"my-feature-flag"` |
|
||||
| `description` | No | The feature flag's description. Defaults to an empty string. | `"Turn my feature on!"` |
|
||||
| `impressionData` | No | Whether to enable [impression data](/reference/impression-data.md) for this flag. Defaults to `false.` | `true` |
|
||||
| `type` | No | The [type of flag](/reference/feature-toggle-types.md) you want to create. Defaults to `"release"` | `"release"` |
|
||||
|
||||
|
||||
**Example Query**
|
||||
|
||||
```bash
|
||||
echo '{"name": "demo2", "description": "A new feature toggle"}' | \
|
||||
echo '{"name": "demo2", "description": "A new feature flag"}' | \
|
||||
http POST http://localhost:4242/api/admin/projects/default/features \
|
||||
Authorization:$KEY`
|
||||
```
|
||||
@ -199,7 +199,7 @@ Vary: Accept-Encoding
|
||||
|
||||
{
|
||||
"createdAt": "2021-09-07T20:16:02.614Z",
|
||||
"description": "A new feature toggle",
|
||||
"description": "A new feature flag",
|
||||
"lastSeenAt": null,
|
||||
"name": "demo2",
|
||||
"project": "default",
|
||||
@ -211,15 +211,15 @@ Vary: Accept-Encoding
|
||||
|
||||
Possible Errors:
|
||||
|
||||
- _409 Conflict_ - A toggle with that name already exists
|
||||
- _409 Conflict_ - A flag with that name already exists
|
||||
|
||||
|
||||
|
||||
### Get Feature Toggle {#get-toggle}
|
||||
### Get Feature Flag {#get-toggle}
|
||||
|
||||
<ApiRequest verb="get" url="api/admin/projects/:projectId/features/:featureName" title="Retrieve a named feature toggle"/>
|
||||
<ApiRequest verb="get" url="api/admin/projects/:projectId/features/:featureName" title="Retrieve a named feature flag"/>
|
||||
|
||||
This endpoint will return the feature toggles with the defined name and _projectId_. We will also see the list of environments and all activation strategies configured per environment.
|
||||
This endpoint will return the feature flags with the defined name and _projectId_. We will also see the list of environments and all activation strategies configured per environment.
|
||||
|
||||
**Example Query**
|
||||
|
||||
@ -265,18 +265,18 @@ Authorization:$KEY`
|
||||
|
||||
Possible Errors:
|
||||
|
||||
- _404 Not Found_ - Could not find feature toggle with the provided name.
|
||||
- _404 Not Found_ - Could not find feature flag with the provided name.
|
||||
|
||||
### Update Feature Toggle {#update-toggle}
|
||||
### Update Feature Flag {#update-toggle}
|
||||
|
||||
<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName" title="Update a feature toggle entry (example data)" payload={{ name: "demo", description: "An updated feature toggle description." }}/>
|
||||
<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName" title="Update a feature flag entry (example data)" payload={{ name: "demo", description: "An updated feature flag description." }}/>
|
||||
|
||||
This endpoint will accept HTTP PUT request to update the feature toggle metadata.
|
||||
This endpoint will accept HTTP PUT request to update the feature flag metadata.
|
||||
|
||||
**Example Query**
|
||||
|
||||
```bash
|
||||
echo '{"name": "demo", "description": "An update feature toggle", "type": "kill-switch"}' | \
|
||||
echo '{"name": "demo", "description": "An update feature flag", "type": "kill-switch"}' | \
|
||||
http PUT http://localhost:4242/api/admin/projects/default/features/demo \
|
||||
Authorization:$KEY`
|
||||
```
|
||||
@ -287,7 +287,7 @@ Authorization:$KEY`
|
||||
```json
|
||||
{
|
||||
"createdAt": "2021-09-07T20:16:02.614Z",
|
||||
"description": "An update feature toggle",
|
||||
"description": "An update feature flag",
|
||||
"lastSeenAt": null,
|
||||
"name": "demo",
|
||||
"project": "default",
|
||||
@ -304,12 +304,12 @@ Some fields is not possible to change via this endpoint:
|
||||
- createdAt
|
||||
- lastSeen
|
||||
|
||||
## Patch Feature Toggle {#patch-toggle}
|
||||
## Patch Feature Flag {#patch-toggle}
|
||||
|
||||
|
||||
<ApiRequest verb="patch" url="api/admin/projects/:projectId/features/:featureName" title="Patch a feature toggle (example data)" payload={[{op: "replace", path: "/description", value: "patched description"}]}/>
|
||||
<ApiRequest verb="patch" url="api/admin/projects/:projectId/features/:featureName" title="Patch a feature flag (example data)" payload={[{op: "replace", path: "/description", value: "patched description"}]}/>
|
||||
|
||||
This endpoint will accept HTTP PATCH request to update the feature toggle metadata.
|
||||
This endpoint will accept HTTP PATCH request to update the feature flag metadata.
|
||||
|
||||
**Example Query**
|
||||
|
||||
@ -343,11 +343,11 @@ Some fields is not possible to change via this endpoint:
|
||||
- lastSeen
|
||||
|
||||
|
||||
### Clone Feature Toggle {#clone-toggle}
|
||||
### Clone Feature Flag {#clone-toggle}
|
||||
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features/:featureName/clone" title="Clone a feature toggle (example data)" payload={{ name: "newToggleName"}}/>
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features/:featureName/clone" title="Clone a feature flag (example data)" payload={{ name: "newFlagName"}}/>
|
||||
|
||||
This endpoint will accept HTTP POST request to clone an existing feature toggle with all strategies and variants. When cloning a toggle, you **must** provide a new name for it. You can not clone archived feature toggles. The newly created feature toggle will be disabled for all environments.
|
||||
This endpoint will accept HTTP POST request to clone an existing feature flag with all strategies and variants. When cloning a flag, you **must** provide a new name for it. You can not clone archived feature flags. The newly created feature flag will be disabled for all environments.
|
||||
|
||||
**Example Query**
|
||||
|
||||
@ -394,14 +394,14 @@ Vary: Accept-Encoding
|
||||
|
||||
Possible Errors:
|
||||
|
||||
- _409 Conflict_ - A toggle with that name already exists
|
||||
- _409 Conflict_ - A flag with that name already exists
|
||||
|
||||
|
||||
### Archive Feature Toggle {#archive-toggle}
|
||||
### Archive Feature Flag {#archive-toggle}
|
||||
|
||||
<ApiRequest verb="delete" url="api/admin/projects/:projectId/features/:featureName" title="Archive a named feature toggle"/>
|
||||
<ApiRequest verb="delete" url="api/admin/projects/:projectId/features/:featureName" title="Archive a named feature flag"/>
|
||||
|
||||
This endpoint will accept HTTP DELETE requests to archive a feature toggle.
|
||||
This endpoint will accept HTTP DELETE requests to archive a feature flag.
|
||||
|
||||
**Example Query**
|
||||
|
||||
@ -423,9 +423,9 @@ Transfer-Encoding: chunked
|
||||
```
|
||||
|
||||
|
||||
### Add strategy to Feature Toggle {#add-strategy}
|
||||
### Add strategy to Feature Flag {#add-strategy}
|
||||
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies" title="Add a new strategy to the named feature toggle in the named environment (example data)" payload={{name: "flexibleRollout",
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies" title="Add a new strategy to the named feature flag in the named environment (example data)" payload={{name: "flexibleRollout",
|
||||
parameters: {
|
||||
rollout: 20,
|
||||
groupId: "demo",
|
||||
@ -433,7 +433,7 @@ Transfer-Encoding: chunked
|
||||
}
|
||||
}}/>
|
||||
|
||||
This endpoint will allow you to add a new strategy to a feature toggle in a given environment.
|
||||
This endpoint will allow you to add a new strategy to a feature flag in a given environment.
|
||||
|
||||
**Example Query**
|
||||
|
||||
@ -467,7 +467,7 @@ Authorization:$KEY
|
||||
|
||||
### Update strategy configuration {#update-strategy}
|
||||
|
||||
<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/:strategy-id" title="Overwrite the specified strategy on the named feature toggle in the named environment (example data)" payload={{name: "flexibleRollout",
|
||||
<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/:strategy-id" title="Overwrite the specified strategy on the named feature flag in the named environment (example data)" payload={{name: "flexibleRollout",
|
||||
parameters: {
|
||||
rollout: 25,
|
||||
groupId: "demo",
|
||||
@ -534,7 +534,7 @@ Authorization:$KEY
|
||||
```
|
||||
|
||||
|
||||
### Delete strategy from Feature Toggle {#delete-strategy}
|
||||
### Delete strategy from Feature Flag {#delete-strategy}
|
||||
|
||||
<ApiRequest verb="delete" url="api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/:strategyId" title="Delete the strategy with the given ID"/>
|
||||
|
||||
@ -557,11 +557,11 @@ Transfer-Encoding: chunked
|
||||
Vary: Accept-Encoding
|
||||
```
|
||||
|
||||
## Enabling and disabling toggles
|
||||
## Enabling and disabling flags
|
||||
|
||||
### Enable Feature Toggle in an Environment {#enable-env}
|
||||
### Enable Feature Flag in an Environment {#enable-env}
|
||||
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features/:featureName/environments/:environment/on" title="Activate the named toggle in the given environment"/>
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features/:featureName/environments/:environment/on" title="Activate the named flag in the given environment"/>
|
||||
|
||||
**Example Query**
|
||||
|
||||
@ -585,9 +585,9 @@ Possible Errors:
|
||||
- _409 Conflict_ - You can not enable the environment before it has strategies.
|
||||
|
||||
|
||||
### Disable Feature Toggle in an Environment {#disable-env}
|
||||
### Disable Feature Flag in an Environment {#disable-env}
|
||||
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features/:featureName/environments/:environment/off" title="Disable the named toggle in the given environment"/>
|
||||
<ApiRequest verb="post" url="api/admin/projects/:projectId/features/:featureName/environments/:environment/off" title="Disable the named flag in the given environment"/>
|
||||
|
||||
**Example Query**
|
||||
|
||||
@ -609,7 +609,7 @@ Transfer-Encoding: chunked
|
||||
|
||||
## Feature Variants
|
||||
|
||||
### Put variants for Feature Toggle {#update-variants}
|
||||
### Put variants for Feature Flag {#update-variants}
|
||||
|
||||
:::caution
|
||||
|
||||
@ -619,7 +619,7 @@ This endpoint affects all environments at once. If you only want to update a sin
|
||||
|
||||
:::
|
||||
|
||||
<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName/variants" title="Create (overwrite) variants for a feature toggle in all environments (example data)" payload={[
|
||||
<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName/variants" title="Create (overwrite) variants for a feature flag in all environments (example data)" payload={[
|
||||
{
|
||||
"name": "variant1",
|
||||
"weightType": "fix",
|
||||
@ -641,7 +641,7 @@ This endpoint affects all environments at once. If you only want to update a sin
|
||||
}
|
||||
]}/>
|
||||
|
||||
This overwrites the current variants for the feature toggle specified in the :featureName parameter.
|
||||
This overwrites the current variants for the feature flag specified in the :featureName parameter.
|
||||
The backend will validate the input for the following invariants
|
||||
|
||||
* If there are variants, there needs to be at least one variant with `weightType: variable`
|
||||
@ -703,7 +703,7 @@ Content-Type: application/json; charset=utf-8
|
||||
}
|
||||
```
|
||||
|
||||
### PATCH variants for a feature toggle
|
||||
### PATCH variants for a feature flag
|
||||
|
||||
:::caution
|
||||
|
||||
@ -713,7 +713,7 @@ This endpoint affects all environments at once. If you only want to update a sin
|
||||
|
||||
:::
|
||||
|
||||
<ApiRequest verb="patch" url="api/admin/projects/:projectId/features/:featureName/variants" title="Patch variants for a feature toggle in all environments (example data)" payload={[{"op": "add", "path": "/1", "value": {
|
||||
<ApiRequest verb="patch" url="api/admin/projects/:projectId/features/:featureName/variants" title="Patch variants for a feature flag in all environments (example data)" payload={[{"op": "add", "path": "/1", "value": {
|
||||
"name": "new-variant",
|
||||
"weightType": "fix",
|
||||
"weight": 200
|
||||
|
||||
@ -24,18 +24,18 @@ The event properties are described in short in the table below. For more info re
|
||||
| Property | Description |
|
||||
| --- | --- |
|
||||
| `createdAt` | The time the event happened as a RFC 3339-conformant timestamp. |
|
||||
| `data` | Extra associated data related to the event, such as feature toggle state, segment configuration, etc., if applicable. |
|
||||
| `environment` | The feature toggle environment the event relates to, if applicable. |
|
||||
| `featureName` | The name of the feature toggle the event relates to, if applicable. |
|
||||
| `data` | Extra associated data related to the event, such as feature flag state, segment configuration, etc., if applicable. |
|
||||
| `environment` | The feature flag environment the event relates to, if applicable. |
|
||||
| `featureName` | The name of the feature flag the event relates to, if applicable. |
|
||||
| `id` | The ID of the event. An increasing natural number. |
|
||||
| `preData` | Data relating to the previous state of the event's subject. |
|
||||
| `project` | The project the event relates to, if applicable. |
|
||||
| `tags` | Any tags related to the event, if applicable. |
|
||||
| `type` | The event type, as described in the rest of this section. |
|
||||
|
||||
## Feature toggle events
|
||||
## Feature flag events
|
||||
|
||||
These events pertain to feature toggles and their life cycle.
|
||||
These events pertain to feature flags and their life cycle.
|
||||
|
||||
### `feature-created`
|
||||
|
||||
@ -49,7 +49,7 @@ This event fires when you create a feature. The `data` property contains the det
|
||||
"createdAt": "2022-05-31T13:32:20.560Z",
|
||||
"data": {
|
||||
"name": "new-feature",
|
||||
"description": "Toggle description",
|
||||
"description": "Flag description",
|
||||
"type": "release",
|
||||
"project": "my-project",
|
||||
"stale": false,
|
||||
@ -74,7 +74,7 @@ This event type was replaced by more granular event types in Unleash 4.3. From U
|
||||
|
||||
:::
|
||||
|
||||
This event fires when a feature gets updated in some way. The `data` property contains the new state of the toggle. This is a legacy event, so it does not populate `preData` property.
|
||||
This event fires when a feature gets updated in some way. The `data` property contains the new state of the flag. This is a legacy event, so it does not populate `preData` property.
|
||||
|
||||
```json title="example event: feature-updated"
|
||||
{
|
||||
@ -84,7 +84,7 @@ This event fires when a feature gets updated in some way. The `data` property co
|
||||
"createdAt": "2022-05-31T13:32:20.560Z",
|
||||
"data": {
|
||||
"name": "new-feature",
|
||||
"description": "Toggle description",
|
||||
"description": "Flag description",
|
||||
"type": "release",
|
||||
"project": "my-project",
|
||||
"stale": false,
|
||||
@ -103,7 +103,7 @@ This event fires when a feature gets updated in some way. The `data` property co
|
||||
|
||||
### `feature-deleted`
|
||||
|
||||
This event fires when you delete a feature toggle. The `preData` property contains the deleted toggle data.
|
||||
This event fires when you delete a feature flag. The `preData` property contains the deleted flag data.
|
||||
|
||||
```json title="example event: feature-deleted"
|
||||
{
|
||||
@ -120,7 +120,7 @@ This event fires when you delete a feature toggle. The `preData` property contai
|
||||
"variants": [],
|
||||
"createdAt": "2022-05-31T13:32:20.547Z",
|
||||
"lastSeenAt": null,
|
||||
"description": "Toggle description",
|
||||
"description": "Flag description",
|
||||
"impressionData": true
|
||||
},
|
||||
"tags": [],
|
||||
@ -132,7 +132,7 @@ This event fires when you delete a feature toggle. The `preData` property contai
|
||||
|
||||
### `feature-archived`
|
||||
|
||||
This event fires when you archive a toggle.
|
||||
This event fires when you archive a flag.
|
||||
|
||||
```json title="example event: feature-archived"
|
||||
{
|
||||
@ -151,7 +151,7 @@ This event fires when you archive a toggle.
|
||||
|
||||
### `feature-revived`
|
||||
|
||||
This event fires when you revive an archived feature toggle (when you take a toggle out from the archive).
|
||||
This event fires when you revive an archived feature flag (when you take a flag out from the archive).
|
||||
|
||||
```json title="example-event: feature-revived"
|
||||
{
|
||||
@ -170,9 +170,9 @@ This event fires when you revive an archived feature toggle (when you take a tog
|
||||
|
||||
### `feature-metadata-updated`
|
||||
|
||||
This event fires when a feature's metadata (its description, toggle type, or impression data settings) are changed. The `data` property contains the new toggle data. The `preData` property contains the toggle's previous data.
|
||||
This event fires when a feature's metadata (its description, flag type, or impression data settings) are changed. The `data` property contains the new flag data. The `preData` property contains the flag's previous data.
|
||||
|
||||
The below example changes the toggle's type from _release_ to _experiment_.
|
||||
The below example changes the flag's type from _release_ to _experiment_.
|
||||
|
||||
```json title="example event: feature-metadata-updated"
|
||||
{
|
||||
@ -182,7 +182,7 @@ The below example changes the toggle's type from _release_ to _experiment_.
|
||||
"createdAt": "2022-05-31T13:35:25.244Z",
|
||||
"data": {
|
||||
"name": "new-feature",
|
||||
"description": "Toggle description",
|
||||
"description": "Flag description",
|
||||
"type": "experiment",
|
||||
"project": "my-project",
|
||||
"stale": false,
|
||||
@ -199,7 +199,7 @@ The below example changes the toggle's type from _release_ to _experiment_.
|
||||
"variants": [],
|
||||
"createdAt": "2022-05-31T13:32:20.547Z",
|
||||
"lastSeenAt": null,
|
||||
"description": "Toggle description",
|
||||
"description": "Flag description",
|
||||
"impressionData": true
|
||||
},
|
||||
"tags": [],
|
||||
@ -284,7 +284,7 @@ This event fires when you add a tag to a feature. The `data` property contains t
|
||||
|
||||
### `feature-untagged`
|
||||
|
||||
This event fires when you remove a tag from a toggle. The `data` property contains the tag that was removed.
|
||||
This event fires when you remove a tag from a flag. The `data` property contains the tag that was removed.
|
||||
|
||||
```json title="example event: feature-untagged"
|
||||
{
|
||||
@ -580,7 +580,7 @@ This event fires when you drop all existing tags as part of a configuration impo
|
||||
|
||||
:::
|
||||
|
||||
This event fires when Unleash marks a feature toggle as potentially stale. Feature toggles are marked as potentially stale when they exceed the expected lifetime of their [feature toggle type](/reference/feature-toggle-types.md).
|
||||
This event fires when Unleash marks a feature flag as potentially stale. Feature flags are marked as potentially stale when they exceed the expected lifetime of their [feature flag type](/reference/feature-toggle-types.md).
|
||||
|
||||
``` json title="Example event when my-feature is marked as potentially stale"
|
||||
{
|
||||
@ -724,7 +724,7 @@ This event fires when you import a strategy as part of an import job. The `data`
|
||||
"createdAt": "2022-06-03T11:30:40.583Z",
|
||||
"data": {
|
||||
"name": "gradualRolloutSessionId",
|
||||
"description": "Gradually activate feature toggle. Stickiness based on session id.",
|
||||
"description": "Gradually activate feature flag. Stickiness based on session id.",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "percentage",
|
||||
@ -735,7 +735,7 @@ This event fires when you import a strategy as part of an import job. The `data`
|
||||
{
|
||||
"name": "groupId",
|
||||
"type": "string",
|
||||
"description": "Used to define a activation groups, which allows you to correlate across feature toggles.",
|
||||
"description": "Used to define a activation groups, which allows you to correlate across feature flags.",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
|
||||
@ -5,7 +5,7 @@ title: Datadog
|
||||
|
||||
> This feature was introduced in _Unleash v4.0.0_.
|
||||
|
||||
The Datadog integration allows Unleash to post Updates to Datadog when a feature toggle is updated. To set up this integration, you need to set up a webhook connector for your channel. You can follow [Submitting events to Datadog](https://docs.datadoghq.com/api/latest/events/#post-an-event) on how to do that.
|
||||
The Datadog integration allows Unleash to post Updates to Datadog when a feature flag is updated. To set up this integration, you need to set up a webhook connector for your channel. You can follow [Submitting events to Datadog](https://docs.datadoghq.com/api/latest/events/#post-an-event) on how to do that.
|
||||
|
||||
The Datadog integration will perform a single retry if the HTTP POST against the Datadog Webhook URL fails (either a 50x or network error). Duplicate events may happen, and you should never assume events always comes in order.
|
||||
|
||||
@ -83,7 +83,7 @@ If you don't specify anything Unleash will send a formatted markdown body.
|
||||
Example:
|
||||
|
||||
```markdown
|
||||
username created feature toggle (featurename)[http://your.url/projects/projectname/features/featurename] in project *projectname*
|
||||
username created feature flag (featurename)[http://your.url/projects/projectname/features/featurename] in project *projectname*
|
||||
```
|
||||
|
||||
#### Tags {#tags}
|
||||
|
||||
@ -15,14 +15,14 @@ When running Unleash, we collect the following data:
|
||||
**Feature Usage Data**: Starting from **Unleash 5.3**, we collect additional data related to feature usage in Unleash.
|
||||
|
||||
This includes the following data points:
|
||||
- The number of active feature toggles in use
|
||||
- The number of active feature flags in use
|
||||
- The total number of users in the system
|
||||
- The total number of projects in the system
|
||||
- The number of custom context fields defined and in use
|
||||
- The number of user groups defined in the system
|
||||
- The number of custom roles defined in the system
|
||||
- The number of environments defined in the system
|
||||
- The number of segments in active use by feature toggles
|
||||
- The number of segments in active use by feature flags
|
||||
- The number of custom strategies defined and in use
|
||||
- The number of feature exports/imports made
|
||||
|
||||
|
||||
@ -81,11 +81,11 @@ You'll need to configure Edge and the SDKs.
|
||||
### On Unleash
|
||||
|
||||
- Create one or multiple [client API tokens](https://docs.getunleash.io/reference/api-tokens-and-client-keys#client-tokens) scoped to the projects/environments you wish to leverage the Edge instance for. (Refer to [how to create API tokens](https://docs.getunleash.io/how-to/how-to-create-api-tokens) for the steps to create one)
|
||||
- Create frontend tokens for the frontend apps that will retrieve feature toggles from Edge
|
||||
- Create frontend tokens for the frontend apps that will retrieve feature flags from Edge
|
||||
|
||||
### On Edge
|
||||
|
||||
Edge will fetch feature toggles from the specified upstream Unleash instance for every client API key it has been made aware of, either during startup (recommended) or separate endpoint requests. It will then periodically sync features with upstream.
|
||||
Edge will fetch feature flags from the specified upstream Unleash instance for every client API key it has been made aware of, either during startup (recommended) or separate endpoint requests. It will then periodically sync features with upstream.
|
||||
|
||||
It will then accept frontend / backend tokens from application SDKs.
|
||||
|
||||
@ -93,11 +93,11 @@ It will then accept frontend / backend tokens from application SDKs.
|
||||
|
||||
Make sure to use the correct token type for the use case:
|
||||
Frontend API: Frontend facing apps only, Edge returns app specific context
|
||||
Client API: For backend SDKs, Edge returns entire toggle payload for scope of token (project/environment)
|
||||
Client API: For backend SDKs, Edge returns entire flag payload for scope of token (project/environment)
|
||||
|
||||
:::
|
||||
**Start Edge & populate toggle cache**
|
||||
- This initial command will populate toggle cache on startup using the client token specified in the environment variable:
|
||||
**Start Edge & populate flag cache**
|
||||
- This initial command will populate flag cache on startup using the client token specified in the environment variable:
|
||||
|
||||
```docker run -p 3063:3063 -e TOKENS='CLIENT_API_TOKEN' -e UPSTREAM_URL='UPSTREAM_URL' unleashorg/unleash-edge:v8.1 edge```
|
||||
|
||||
|
||||
@ -3,9 +3,9 @@ title: The Anatomy of Unleash
|
||||
---
|
||||
import Figure from '@site/src/components/Figure/Figure.tsx'
|
||||
|
||||
This guide's purpose is to give you a conceptual overview of how Unleash works. It covers the various components that exist within an Unleash system and how they interact with each other and with external applications. The diagrams are intended to help you understand the fundamental building blocks, such as [projects](../reference/projects.md), [environments](../reference/environments.md), [variants](../reference/feature-toggle-variants.md) and, of course, [feature toggles](../reference/feature-toggles.mdx).
|
||||
This guide's purpose is to give you a conceptual overview of how Unleash works. It covers the various components that exist within an Unleash system and how they interact with each other and with external applications. The diagrams are intended to help you understand the fundamental building blocks, such as [projects](../reference/projects.md), [environments](../reference/environments.md), [variants](../reference/feature-toggle-variants.md) and, of course, [feature flags](../reference/feature-toggles.mdx).
|
||||
|
||||
The end of this guide presents a [short use case, explaining how you might configure Unleash](#use-case) to start working with feature toggles.
|
||||
The end of this guide presents a [short use case, explaining how you might configure Unleash](#use-case) to start working with feature flags.
|
||||
|
||||
|
||||
## The root level
|
||||
@ -23,7 +23,7 @@ Some things in Unleash are configured and defined on the root level. These optio
|
||||
|
||||
## Projects
|
||||
|
||||
[**Projects**](../reference/projects.md) contain [feature toggles](../reference/feature-toggles.mdx) and their configurations, and a set of active [environments](../reference/environments.md).
|
||||
[**Projects**](../reference/projects.md) contain [feature flags](../reference/feature-toggles.mdx) and their configurations, and a set of active [environments](../reference/environments.md).
|
||||
|
||||
All Unleash instances must have at least one project at any given time. New instances get a project called “Default”.
|
||||
|
||||
@ -33,9 +33,9 @@ Pro and Enterprise customers can create, rename, and delete projects as they wis
|
||||
|
||||
## Environments and project environments
|
||||
|
||||
<Figure img="/img/anatomy-of-unleash-customer-tiers.png" caption="Feature toggles can be activated or deactivated independently in different environments. For instance, a feature toggle can be active in the development environment, and deactivated in the production environment. Even if their configuration is otherwise identical, deactivated feature toggles will never be considered enabled."/>
|
||||
<Figure img="/img/anatomy-of-unleash-customer-tiers.png" caption="Feature flags can be activated or deactivated independently in different environments. For instance, a feature flag can be active in the development environment, and deactivated in the production environment. Even if their configuration is otherwise identical, deactivated feature flags will never be considered enabled."/>
|
||||
|
||||
[**Environments**](../reference/environments.md) in Unleash let you change how a feature toggle works in your application’s different environments. For instance, while you are developing a feature, it’s likely that you’ll want it to be available in your development environment, but not in your production environment: environments let you do that. You might also want to enable a feature for only some users in your development environment, but no users in your production environment: environments let you do that.
|
||||
[**Environments**](../reference/environments.md) in Unleash let you change how a feature flag works in your application’s different environments. For instance, while you are developing a feature, it’s likely that you’ll want it to be available in your development environment, but not in your production environment: environments let you do that. You might also want to enable a feature for only some users in your development environment, but no users in your production environment: environments let you do that.
|
||||
|
||||
Environments exist on two different levels within Unleash. The set of **all available environments is defined on the root level**. Additionally, **each project** can choose which of these root environments should be **available on the project level**. The set of environments available to any given project is **always a subset** of the set of all available environments at the root level.
|
||||
|
||||
@ -43,7 +43,7 @@ Each project must always have **at least one** active environment.
|
||||
|
||||
Enterprise users can create and remove environments. Open-source and Pro customers get access to two environments: **development** and **production.**
|
||||
|
||||
Environments are adjacent to [feature toggles](../reference/feature-toggles.mdx) in Unleash: neither one contains the other, but they come together to let you define activation strategies.
|
||||
Environments are adjacent to [feature flags](../reference/feature-toggles.mdx) in Unleash: neither one contains the other, but they come together to let you define activation strategies.
|
||||
|
||||
<Figure img="/img/anatomy-of-unleash-new-feature-rollout.png" caption="You can use different activation strategies and constraints in different environments. For instance, you can show a feature only to select user IDs in development, but roll it out to 25% of your user base in production."/>
|
||||
|
||||
@ -54,32 +54,32 @@ When connecting an SDK to Unleash, it's the **API key that decides which environ
|
||||
:::
|
||||
|
||||
|
||||
## Features (feature toggles)
|
||||
## Features (feature flags)
|
||||
|
||||
[**Feature toggles**](../reference/feature-toggles.mdx) are at the heart of Unleash’s functionality. Feature toggles belong to projects and live next to project environments. In and of itself, a feature toggle doesn’t do anything. You must assign [**activation strategies**](../reference/activation-strategies.md) to it for it to start taking effect.
|
||||
[**Feature flags**](../reference/feature-toggles.mdx) are at the heart of Unleash’s functionality. Feature flags belong to projects and live next to project environments. In and of itself, a feature flag doesn’t do anything. You must assign [**activation strategies**](../reference/activation-strategies.md) to it for it to start taking effect.
|
||||
|
||||
When creating a feature toggle, you must assign a unique (across your Unleash instance) name, a [feature toggle type](../reference/feature-toggle-types.md), a [project](../reference/projects.md) it belongs to, and an optional description. Everything except for the name can be changed later.
|
||||
When creating a feature flag, you must assign a unique (across your Unleash instance) name, a [feature flag type](../reference/feature-toggle-types.md), a [project](../reference/projects.md) it belongs to, and an optional description. Everything except for the name can be changed later.
|
||||
|
||||
<Figure img="/img/anatomy-of-unleash-features.png" caption="Feature toggle states are evaluated independently in each environment." alt="A hierarchy showing a project containing an environment containing a feature toggle configuration."/>
|
||||
<Figure img="/img/anatomy-of-unleash-features.png" caption="Feature flag states are evaluated independently in each environment." alt="A hierarchy showing a project containing an environment containing a feature flag configuration."/>
|
||||
|
||||
## Activation strategies
|
||||
|
||||
<Figure img="/img/anatomy-of-unleash-strategy.png" caption="Activation strategies are applied to feature toggles on a per-environment basis and decide whether a feature is enabled or not." alt="A hierarchy displaying an environment containing a feature toggle configuration with an activation strategy."/>
|
||||
<Figure img="/img/anatomy-of-unleash-strategy.png" caption="Activation strategies are applied to feature flags on a per-environment basis and decide whether a feature is enabled or not." alt="A hierarchy displaying an environment containing a feature flag configuration with an activation strategy."/>
|
||||
|
||||
[**Activation strategies**](../reference/activation-strategies.md) (or just **strategies** for short) are the part of feature toggles that tell Unleash **who should get a feature**. An activation strategy is assigned to **one **feature toggle in **one **environment.
|
||||
[**Activation strategies**](../reference/activation-strategies.md) (or just **strategies** for short) are the part of feature flags that tell Unleash **who should get a feature**. An activation strategy is assigned to **one **feature flag in **one **environment.
|
||||
|
||||
When you check a [feature toggle](../reference/feature-toggles.mdx) in an application, the following decides the result:
|
||||
1. Is the toggle active in the current environment? If not, it will be disabled.
|
||||
2. If the toggle **is** active in the current environment, the toggle’s strategies decide the result. As long as **at least one** of a toggle’s strategies resolve to true for the current context (user or application), then the toggle will be considered enabled. In other words, if you have a hundred strategies and ninety-nine of them resolve to false, but one of them resolves to true, then the toggle is enabled.
|
||||
When you check a [feature flag](../reference/feature-toggles.mdx) in an application, the following decides the result:
|
||||
1. Is the flag active in the current environment? If not, it will be disabled.
|
||||
2. If the flag **is** active in the current environment, the flag’s strategies decide the result. As long as **at least one** of a flag’s strategies resolve to true for the current context (user or application), then the flag will be considered enabled. In other words, if you have a hundred strategies and ninety-nine of them resolve to false, but one of them resolves to true, then the flag is enabled.
|
||||
|
||||
Activation strategies tie feature toggles and [environments](../reference/environments.md) together. When you assign an activation strategy to a feature toggle, you do so in one environment at a time. You can assign the same strategy to the same toggle in different environments, but they will be different instances of the same strategy, and do not stay in sync. Unleash also lets you copy strategies from one environment to another.
|
||||
Activation strategies tie feature flags and [environments](../reference/environments.md) together. When you assign an activation strategy to a feature flag, you do so in one environment at a time. You can assign the same strategy to the same flag in different environments, but they will be different instances of the same strategy, and do not stay in sync. Unleash also lets you copy strategies from one environment to another.
|
||||
|
||||
Unleash comes with a number of strategies built in (refer the [activation strategies documentation](../reference/activation-strategies.md) for more information on those). You can also create your own [custom activation strategies](../reference/custom-activation-strategies.md) if you need them. All strategies can be further augmented by [**strategy constraints**](../reference/strategy-constraints.md).
|
||||
|
||||
|
||||
<Figure img="/img/anatomy-of-unleash-environments-strategies.png" caption="Feature toggles exist across environments and can have different activation strategies in each environment."/>
|
||||
<Figure img="/img/anatomy-of-unleash-environments-strategies.png" caption="Feature flags exist across environments and can have different activation strategies in each environment."/>
|
||||
|
||||
<Figure img="/img/anatomy-of-unleash-environments-strategies2.png" caption="Feature toggle activation strategies can be copied between environments. You can also create new strategies in each environment."/>
|
||||
<Figure img="/img/anatomy-of-unleash-environments-strategies2.png" caption="Feature flag activation strategies can be copied between environments. You can also create new strategies in each environment."/>
|
||||
|
||||
## Strategy constraints
|
||||
|
||||
@ -93,10 +93,10 @@ An activation strategy can have as many constraints as you want. When an activat
|
||||
|
||||
:::tip Strategies and constraints
|
||||
|
||||
Feature toggle strategies are **permissive**: As long as **one** strategy resolves to true, the feature is considered enabled. On the other hand, constrains are **restrictive**: for a given strategy, **all** constraints must be met for it to resolve to true.
|
||||
Feature flag strategies are **permissive**: As long as **one** strategy resolves to true, the feature is considered enabled. On the other hand, constrains are **restrictive**: for a given strategy, **all** constraints must be met for it to resolve to true.
|
||||
|
||||
We can exemplify this difference with the logical operators AND and OR:
|
||||
- For a feature toggle, if Strategy1 OR Strategy2 OR .. OR StrategyN is true, **then the feature is enabled**.
|
||||
- For a feature flag, if Strategy1 OR Strategy2 OR .. OR StrategyN is true, **then the feature is enabled**.
|
||||
- For a strategy, it can be evaluated **if and only if** Constraint1 AND Constraint2 AND .. AND ConstraintN are met.
|
||||
|
||||
Note that even if all the constraints are met, the strategy itself might not resolve to true: that will depend on the strategy and the provided context.
|
||||
@ -122,27 +122,27 @@ Segments are only available to Pro and Enterprise users.
|
||||
|
||||
<Figure img="/img/anatomy-of-unleash-segments.png" caption="Segments are reusable lists of constraints that can be applied to a strategy instead of or in addition to constraints." />
|
||||
|
||||
## Variants and feature toggle payloads
|
||||
## Variants and feature flag payloads
|
||||
|
||||
By default, a [feature toggle](../reference/feature-toggles.mdx) in Unleash only tells you whether a feature is enabled or disabled, but you can also add more information to your toggles by using [**feature toggle variants**](../reference/feature-toggle-variants.md). Variants also allow you to run [A/B testing experiments](/topics/a-b-testing.md).
|
||||
By default, a [feature flag](../reference/feature-toggles.mdx) in Unleash only tells you whether a feature is enabled or disabled, but you can also add more information to your flags by using [**feature flag variants**](../reference/feature-toggle-variants.md). Variants also allow you to run [A/B testing experiments](/topics/a-b-testing.md).
|
||||
|
||||
Feature toggles are designed to let you decide which users get access to a feature. Variants are designed to let you decide **which version** of the feature a user gets access to. For instance, if user A is part of your beta testing program and gets access to a new beta feature, then you can use variants to decide whether they should get the red version or the green version of the feature.
|
||||
Feature flags are designed to let you decide which users get access to a feature. Variants are designed to let you decide **which version** of the feature a user gets access to. For instance, if user A is part of your beta testing program and gets access to a new beta feature, then you can use variants to decide whether they should get the red version or the green version of the feature.
|
||||
|
||||
When you create new variants for a feature, they must be given a name and a **weighting** indicating how many users should see this particular variant of the feature. They can also be given a **payload**.
|
||||
|
||||
You can use the variant payload to attach arbitrary data to a variant. Variants can have different kinds of payloads.
|
||||
|
||||
A feature toggle can have as many variants as you want.
|
||||
A feature flag can have as many variants as you want.
|
||||
|
||||
### Variants and environments
|
||||
|
||||
Prior to 4.21, variants were independent of [environments](../reference/environments.md). In other words: if you're on 4.19 or lower, you’ll always have the exact same variants with the exact same weightings and the exact same payloads in all environments.
|
||||
|
||||
<Figure img="/img/anatomy-of-unleash-variants.png" caption="Before Unleash 4.21, feature toggle variants were the same for all environments."/>
|
||||
<Figure img="/img/anatomy-of-unleash-variants.png" caption="Before Unleash 4.21, feature flag variants were the same for all environments."/>
|
||||
|
||||
As of version 4.21, a feature can have different variants in different environments. For instance, a development environment might have no variants, while a production environment has 2 variants. Payloads, weightings and anything else can also differ between environments.
|
||||
|
||||
<Figure img="/img/anatomy-of-unleash-variants-per-environment.png" caption="From Unleash 4.21 on, a feature toggle can have different in each environment."/>
|
||||
<Figure img="/img/anatomy-of-unleash-variants-per-environment.png" caption="From Unleash 4.21 on, a feature flag can have different in each environment."/>
|
||||
|
||||
|
||||
## Use case: changing website colors {#use-case}
|
||||
@ -157,9 +157,9 @@ Using the concepts we have looked at in the previous sections, let’s create a
|
||||
|
||||
Assuming you have a brand new Unleash instance, you already have the “Default” project and the “Development” and “Production” environments available. That’s going to be all you need for now.
|
||||
|
||||
First things first, in the Default project, you create a new feature toggle, called “new-color-scheme” (toggle names have to be URL-friendly, so no spaces allowed!).
|
||||
First things first, in the Default project, you create a new feature flag, called “new-color-scheme” (flag names have to be URL-friendly, so no spaces allowed!).
|
||||
|
||||
Because you’d like to see the new color scheme while you’re developing it, you assign a “standard” strategy to the new-color-scheme toggle in the development environment and turn it on.
|
||||
Because you’d like to see the new color scheme while you’re developing it, you assign a “standard” strategy to the new-color-scheme flag in the development environment and turn it on.
|
||||
|
||||
### In your application
|
||||
|
||||
@ -191,7 +191,7 @@ As soon as you enable the production environment, the feature gets rolled out to
|
||||
|
||||
While you were developing the new color scheme, you also dabbled a bit with other colors in addition to blue: green and purple might be nice too! So you decide to create two extra color schemes that you’re happy with. But you’d like to hear what your users think too, so you need to roll it out to them somehow.
|
||||
|
||||
You decide to use feature toggle variants to differentiate between the different themes, creating three variants: blue, green, and purple. You want each of them to roll out to the same number of users, so you leave them equally weighted.
|
||||
You decide to use feature flag variants to differentiate between the different themes, creating three variants: blue, green, and purple. You want each of them to roll out to the same number of users, so you leave them equally weighted.
|
||||
|
||||
```js
|
||||
|
||||
|
||||
@ -22,9 +22,9 @@ Before you can connect your application to Unleash you need a Unleash server. Yo
|
||||
|
||||
|
||||
|
||||
- [**The Unleash API**](/reference/api/unleash) - The Unleash instance. This is where you create feature toggles, configure activation strategies, and parameters, etc. The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
|
||||
- **The Unleash admin UI** - The bundled web interface for interacting with the Unleash instance. Manage toggles, define strategies, look at metrics, and much more. Use the UI to [create feature toggles](how-to/how-to-create-feature-toggles.md), [manage project access roles](../how-to/how-to-create-and-assign-custom-project-roles.md), [create API tokens](how-to/how-to-create-api-tokens.mdx), and more.
|
||||
- [**The Unleash API**](/reference/api/unleash) - The Unleash instance. This is where you create feature flags, configure activation strategies, and parameters, etc. The service holding all feature flags and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
|
||||
- **The Unleash admin UI** - The bundled web interface for interacting with the Unleash instance. Manage flags, define strategies, look at metrics, and much more. Use the UI to [create feature flags](how-to/how-to-create-feature-toggles.md), [manage project access roles](../how-to/how-to-create-and-assign-custom-project-roles.md), [create API tokens](how-to/how-to-create-api-tokens.mdx), and more.
|
||||
- [**Unleash SDKs**](../reference/sdks/index.md) - Unleash SDKs integrate into your applications and get feature configurations from the Unleash API. Use them to check whether features are enabled or disabled and to send metrics to the Unleash API. [See all our SDKs](../reference/sdks/index.md)
|
||||
- [**The Unleash Edge**](../generated/unleash-edge.md) - The Unleash Edge sits between front-end and native applications and the Unleash API, it can also sit between server-side SDKs and the Unleash API as well. You can scale it independently of the Unleash API to handle large request rates without causing issues for the Unleash API. Edge has all endpoints for the client API, frontend API, and proxy API.
|
||||
|
||||
To be super fast (_we're talking nano-seconds_), the [client SDK](../reference/sdks/index.md) caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database.
|
||||
To be super fast (_we're talking nano-seconds_), the [client SDK](../reference/sdks/index.md) caches all feature flags and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a flag is on or off because it is just a simple function operating on local state, without the need to poll data from the database.
|
||||
|
||||
@ -26,19 +26,19 @@ An understanding of Unleash anatomy and architecture and how the different syste
|
||||
---
|
||||
|
||||
|
||||
**Intro to Feature Flags/Toggles & Unleash**
|
||||
**Intro to Feature Flags & Unleash**
|
||||
- Feature flags - What they are & why to use them
|
||||
- What is Unleash?
|
||||
|
||||
**Anatomy of Unleash**
|
||||
- Covering the various components that exist within the Unleash system and how they interact with each other and with external applications. Components that include but not limited to: projects, environments, variants, feature toggles --> strategies, tokens, tags, context
|
||||
- Covering the various components that exist within the Unleash system and how they interact with each other and with external applications. Components that include but not limited to: projects, environments, variants, feature flags --> strategies, tokens, tags, context
|
||||
|
||||
**Architecture overview**
|
||||
- Unleash API, UI, SDKs, Proxy --> Edge (Proxy 2.0)
|
||||
|
||||
**How to use Unleash**
|
||||
- Projects and Environments
|
||||
- Toggle creation and targeting
|
||||
- Flag creation and targeting
|
||||
- Strategies, constraints, segments
|
||||
- Variants (and environments), Strategy Variants
|
||||
- Introduction to A/B Testing
|
||||
|
||||
@ -121,7 +121,7 @@ docker run -p 4242:4242 \
|
||||
|
||||
## Test your server and create a sample API call {#test-your-server-and-create-a-sample-api-call}
|
||||
|
||||
Once the Unleash server has started, go to [localhost:4242](http://localhost:4242) in your browser. If you see an empty list of feature toggles, try creating one with [curl](https://curl.se/) from a terminal/bash shell:
|
||||
Once the Unleash server has started, go to [localhost:4242](http://localhost:4242) in your browser. If you see an empty list of feature flags, try creating one with [curl](https://curl.se/) from a terminal/bash shell:
|
||||
|
||||
```
|
||||
curl --location -H "Authorization: <apitoken from previous step>" \
|
||||
|
||||
@ -43,7 +43,7 @@ This should only impact dev builds and initial setup. You should never use the d
|
||||
|
||||
### The /api/admin/features API is gone
|
||||
|
||||
Most of the old features API was deprecated in v4.3 and superseded by the project API instead. In v5, the deprecated parts have been completely removed. The only operations on that API that are still active are the operations to add or remove a tag from a feature toggle.
|
||||
Most of the old features API was deprecated in v4.3 and superseded by the project API instead. In v5, the deprecated parts have been completely removed. The only operations on that API that are still active are the operations to add or remove a tag from a feature flag.
|
||||
|
||||
### Error message structure
|
||||
|
||||
@ -130,7 +130,7 @@ req.session.user = user;
|
||||
|
||||
Only relevant if you use the `enableLegacyRoutes` option.
|
||||
|
||||
In v2 you could query feature toggles on `/api/features`. This was deprecated in v4 and we introduced two different endpoints (`/api/admin/features` and `/api/client/features`) to be able to optimize performance and security. In v3 you could still enable the legacy routes via the `enableLegacyRoutes` option. This was removed in v4.
|
||||
In v2 you could query feature flags on `/api/features`. This was deprecated in v4 and we introduced two different endpoints (`/api/admin/features` and `/api/client/features`) to be able to optimize performance and security. In v3 you could still enable the legacy routes via the `enableLegacyRoutes` option. This was removed in v4.
|
||||
|
||||
### 5. Unleash CLI has been removed {#5-unleash-cli-has-been-removed}
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ If you're unsure whether the feature flag is being properly returned, you can go
|
||||
|
||||
1. If you're using a [gradual rollout activation strategy](/reference/activation-strategies#gradual-rollout) be sure to set the rollout percentage to the percentage of your user base you would like to target for the test. If you would like to target 100% of your user base on your A/B/n test, confirm that your rollout percentage is set to 100%. Alternatively, you may want to consider using a [standard strategy](/reference/activation-strategies#standard) instead, since that means "active for everyone". This adjustment guarantees that all users participate in the A/B/n test, irrespective of the division ratio, be it an even 50-50 split, for a typical A/B test with 50% for Group A and 50% for Group B, or any other distribution that you configure in your variants.
|
||||
2. When using a [gradual rollout strategy](/reference/activation-strategies#gradual-rollout), be mindful of the [stickiness](/reference/stickiness) value. If you're using default stickiness, confirm that either `userId` or `sessionId` are part of your context to ensure consistent results. Besides, if the provided context does not include the field used in the stickiness configuration, the gradual rollout strategy will be evaluated to `false` and therefore it will not be returned by the API.
|
||||
3. Ensure that your variants are correctly configured. You can refer to [feature toggle variants](/reference/feature-toggle-variants). For example, if you would like to run a simple 50-50 A/B test, then your variants should look similar to this:
|
||||
3. Ensure that your variants are correctly configured. You can refer to [feature flag variants](/reference/feature-toggle-variants). For example, if you would like to run a simple 50-50 A/B test, then your variants should look similar to this:
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user