From e6d735554bc7cea023e572b543476f7f9225da7e Mon Sep 17 00:00:00 2001 From: Nnenna Ndukwe Date: Fri, 27 Sep 2024 09:35:39 -0400 Subject: [PATCH] rebase with new a/b testing doc BEFORE merging this --- .../how-to/how-to-capture-impression-data.mdx | 34 ++++--- .../the-anatomy-of-unleash.mdx | 96 ++++++++++++------- 2 files changed, 85 insertions(+), 45 deletions(-) diff --git a/website/docs/how-to/how-to-capture-impression-data.mdx b/website/docs/how-to/how-to-capture-impression-data.mdx index ad380f8e26ea..362602f8fdac 100644 --- a/website/docs/how-to/how-to-capture-impression-data.mdx +++ b/website/docs/how-to/how-to-capture-impression-data.mdx @@ -1,25 +1,26 @@ --- title: How to capture impression data --- -import ApiRequest from '@site/src/components/ApiRequest' -import VideoContent from '@site/src/components/VideoContent.jsx' + +import ApiRequest from "@site/src/components/ApiRequest"; +import VideoContent from "@site/src/components/VideoContent.jsx"; :::info Placeholders Placeholders in the code samples below are delimited by angle brackets (i.e. ``). 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 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). +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](../feature-flag-tutorials/use-cases/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. - + ## Prerequisites 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 **``**. -- **what format the data needs to be in**. This will determine how you transform the event data before you send it. +- **where to send the data to**. We'll refer to this in the code samples below as **``**. +- **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 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). @@ -37,7 +38,12 @@ When you create a new feature flag via the UI, there's an option at the end of t 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). -", impressionData: true}} url="api/admin/projects//features" title="Create a feature flag with impression data enabled."/> +", impressionData: true }} + url="api/admin/projects//features" + title="Create a feature flag with impression data enabled." +/> ### Enabling impression data for existing feature flags {#step-1-existing-toggles} @@ -47,8 +53,12 @@ To enable impression data for an existing flag, go to the "Settings" tab of that 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): - - + ## Step 2: Capture impression events in your client {#step-2} @@ -58,7 +68,7 @@ The steps below will use extracts from said documentation. After initializing the library, you'll probably also want to identify the current user, so that events can be correlated properly: -``` js title="Identify the user." +```js title="Identify the user." posthog.identify(userId); ``` @@ -66,10 +76,9 @@ posthog.identify(userId); Attach an event listener to Unleash that listens for `"impression"` events. Inside the listener, transform the event data to the format you want and send it to your analytics service. -``` js title="Capture, transform, and send impression data." +```js title="Capture, transform, and send impression data." // listen for impression events unleash.on("impression", (event) => { - // capture and transform events posthog.capture(event.eventType, { ...event.context, @@ -78,7 +87,6 @@ unleash.on("impression", (event) => { enabled: event.enabled, variant: event.variant, }); - }); ``` diff --git a/website/docs/understanding-unleash/the-anatomy-of-unleash.mdx b/website/docs/understanding-unleash/the-anatomy-of-unleash.mdx index 6557fd59a552..59cf64755440 100644 --- a/website/docs/understanding-unleash/the-anatomy-of-unleash.mdx +++ b/website/docs/understanding-unleash/the-anatomy-of-unleash.mdx @@ -1,25 +1,24 @@ --- title: The Anatomy of Unleash --- -import Figure from '@site/src/components/Figure/Figure.tsx' + +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 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 flags. - ## The root level Some things in Unleash are configured and defined on the root level. These options apply across the entire Unleash instance. The most important root configuration options for day-to-day operations are: -- [API access tokens](../reference/api-tokens-and-client-keys.mdx) -- [Projects](../reference/projects.md) -- [Segments](../reference/segments.mdx) -- [Strategy types](../reference/activation-strategies.md) (including [custom activation strategy types](../reference/custom-activation-strategies.md)) -- [Tag types](../reference/tags.md) -- [Unleash context](../reference/unleash-context.md) fields (including [custom context fields](../reference/unleash-context.md#custom-context-fields)) -- Users, [user groups](../reference/rbac.md#user-groups) and [roles](../reference/rbac.md) - +- [API access tokens](../reference/api-tokens-and-client-keys.mdx) +- [Projects](../reference/projects.md) +- [Segments](../reference/segments.mdx) +- [Strategy types](../reference/activation-strategies.md) (including [custom activation strategy types](../reference/custom-activation-strategies.md)) +- [Tag types](../reference/tags.md) +- [Unleash context](../reference/unleash-context.md) fields (including [custom context fields](../reference/unleash-context.md#custom-context-fields)) +- Users, [user groups](../reference/rbac.md#user-groups) and [roles](../reference/rbac.md) ## Projects @@ -29,11 +28,18 @@ All Unleash instances must have at least one project at any given time. New inst Pro and Enterprise customers can create, rename, and delete projects as they wish (as long as there is always **at least one project**). Open-source users, on the other hand, only get access to the Default project. -
+
## Environments and project environments -
+
[**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. @@ -45,7 +51,10 @@ Enterprise users can create and remove environments. Open-source and Pro custome 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. -
+
:::info Environments and API keys @@ -53,22 +62,30 @@ When connecting an SDK to Unleash, it's the **API key that decides which environ ::: - -## Features (feature flags) +## Features (feature flags) [**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 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. -
+
## Activation strategies -
+
[**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 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. @@ -76,10 +93,15 @@ Activation strategies tie feature flags and [environments](../reference/environm 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). +
-
- -
+
## Strategy constraints @@ -96,19 +118,23 @@ An activation strategy can have as many constraints as you want. When an activat 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 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. + +- 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. ::: - You can define constraints on whatever properties you want in your [Unleash context](../reference/unleash-context.md). Constraints are applied to individual strategies and do not stay in sync with each other. When you need to have the same constraints applied to multiple strategies and need those constraints to stay in sync, use [**segments**](../reference/segments.mdx). -
+
## Segments @@ -120,11 +146,14 @@ You can apply multiple segments to a strategy. Much like with constraints, **eve Segments are only available to Pro and Enterprise users. -
+
## Variants and feature flag payloads -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). +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](../feature-flag-tutorials/use-cases/a-b-testing.md). 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. @@ -138,12 +167,17 @@ A feature flag can have as many variants as you want. 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. -
+
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. -
- +
## Use case: changing website colors {#use-case} @@ -175,8 +209,7 @@ if (unleash.isEnabled(“new-color-scheme”)) { } ``` -And with that, the new color scheme is now live in your development environment. Because there aren’t any strategies defined in the production environment yet, the feature is not active, and everything is as it was. - +And with that, the new color scheme is now live in your development environment. Because there aren’t any strategies defined in the production environment yet, the feature is not active, and everything is as it was. ### Rolling out the feature to users @@ -186,7 +219,6 @@ You decide to add a _gradual rollout_ strategy to the new-color-scheme feature i As soon as you enable the production environment, the feature gets rolled out to 5% of your users (assuming you’ve deployed the code to production). - ### Adding variants 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.