diff --git a/.gitbook/assets/end-user-opt-in-access.png b/.gitbook/assets/end-user-opt-in-access.png new file mode 100644 index 0000000..f574cf5 Binary files /dev/null and b/.gitbook/assets/end-user-opt-in-access.png differ diff --git a/.gitbook/assets/end-user-opt-in-memberships.png b/.gitbook/assets/end-user-opt-in-memberships.png new file mode 100644 index 0000000..cb7de03 Binary files /dev/null and b/.gitbook/assets/end-user-opt-in-memberships.png differ diff --git a/.gitbook/assets/end-user-opt-in-settings.png b/.gitbook/assets/end-user-opt-in-settings.png new file mode 100644 index 0000000..1afa169 Binary files /dev/null and b/.gitbook/assets/end-user-opt-in-settings.png differ diff --git a/SUMMARY.md b/SUMMARY.md index 5749683..b36d678 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -55,6 +55,7 @@ * [Product overview](product-handbook/product-overview.md) * [Flag rollouts](product-handbook/feature-rollouts/README.md) * [Access rules](product-handbook/feature-rollouts/feature-targeting-rules.md) + * [End-user opt-in](product-handbook/end-user-opt-in.md) * [Flag clean-up and archival](product-handbook/feature-clean-up-and-archival-beta/README.md) * [AI code clean-up](product-handbook/feature-clean-up-and-archival-beta/ai-code-clean-up-beta.md) * [Remote config](product-handbook/remote-config.md) diff --git a/guides/self-opt-in.md b/guides/self-opt-in.md index 5626b96..474a4f3 100644 --- a/guides/self-opt-in.md +++ b/guides/self-opt-in.md @@ -1,17 +1,25 @@ --- -description: How to build a beta feature opt-in page with the Reflag React SDK +description: Build a beta feature opt-in page with the Reflag React SDK icon: browser --- -# Beta feature opt-in +# Build a beta feature opt-in page -Let users opt themselves—or their company—into beta and experimental features with Reflag's React SDK. +Use Reflag's React SDK to let users opt themselves—or their company—into beta and experimental features. + +For an overview of how opt-in affects access and how memberships are managed in Reflag, see [End-user opt-in](../product-handbook/end-user-opt-in.md). + +## Before you begin + +1. [Configure one or more non-secret flags for end-user opt-in](../product-handbook/end-user-opt-in.md#configure-end-user-opt-in). +2. Set **Access** to **Some** in every environment where opting in should be available. +3. Include a `user.id` in the Reflag context for user opt-in. To support company opt-in, also include a `company.id`. ## Quick start -After enabling end-user opt-in on at least one flag in Reflag, render the available flags and let the current user set their opt-in status. +Render the available opt-in flags and let the current user set their opt-in status. -If you're using `` without a `` boundary, see the section below. +If you're using `` without a `` boundary, see the loading section below. ```tsx import { useState } from "react"; @@ -84,17 +92,6 @@ function OptInFlagCard({ flag }: { flag: OptInFlag }) { `useOptInFlags()` keeps the list synchronized with Reflag. `useSetOptIn()` changes the current user's opt-in by default and requires the current Reflag context to include a `user.id`. -## Configure a flag for opt-in - -1. Open a non-secret flag in Reflag. -2. Go to **Settings > Opt-in**. -3. Enable **End-user opt-in**. -4. Optionally add a **Public description**. The SDK exposes this text so you can display it in your opt-in UI. -5. Save your changes. -6. On the flag's **Access** tab, verify that access is set to **Some** in each environment where users should be able to opt in. Leave the other access rules empty for an opt-in-only feature, or add rules to grant access through either targeting or opt-in. - -Secret flags cannot use end-user opt-in because opt-ins are submitted directly from a browser or client using a publishable key. - ## Company opt-in To change the current company's opt-in, pass `scope: "company"`. The current Reflag context must include a `company.id`. @@ -132,4 +129,5 @@ With a regular `ReflagProvider`, opt-in metadata arrives as part of the normal f ## Next steps -Learn how to manage additional access with [Access rules](../product-handbook/feature-rollouts/feature-targeting-rules.md). +* Learn how to view, manage, disable, and re-enable memberships in [End-user opt-in](../product-handbook/end-user-opt-in.md). +* Learn how to grant additional access with [Access rules](../product-handbook/feature-rollouts/feature-targeting-rules.md). diff --git a/product-handbook/end-user-opt-in.md b/product-handbook/end-user-opt-in.md new file mode 100644 index 0000000..1a24f9f --- /dev/null +++ b/product-handbook/end-user-opt-in.md @@ -0,0 +1,114 @@ +--- +description: Let end users opt themselves or their company into beta and experimental features +--- + +# End-user opt-in + +Reflag makes it easy to let end users opt into new, experimental, or beta features. + +Unlike regular [access rules](feature-rollouts/feature-targeting-rules.md), which are controlled entirely by your team, end-user opt-in lets users choose whether they want access. You build the opt-in experience in your product, while Reflag manages opt-in membership and evaluates access. + +## When to use it + +End-user opt-in is useful when you want experienced or adventurous users to try features that are not yet ready for everyone. + +Common use cases include: + +* Experimental or beta features +* Early access programs +* Redesigned parts of your product +* A redesigned version of your entire application +* Optional workflows intended for advanced users + +For redesigns, opt-in lets users move between the old and new experiences themselves while you collect feedback and continue improving the new version. + +## How opt-in affects access + +Opt-in works alongside your existing access rules. A user receives access when they match either: + +* One of the flag's regular access rules +* An active user or company opt-in + +The flag's access setting determines how opt-ins behave: + +| Access setting | Behavior | +| --- | --- | +| **No one** | The flag is off. Existing opt-ins are inactive, and new opt-ins are rejected. | +| **Some** | Access is granted through regular access rules or opt-in membership. | +| **Everyone** | Everyone has access, regardless of opt-in membership. | + +For a feature available exclusively through opt-in, select **Some** and leave the other access rules empty. + +
The Access tab showing opted-in users and companies as an additional access rule

Opt-in membership appears separately from regular access rules and is combined with them using OR.

+ +## Configure end-user opt-in + +To enable opt-in for a flag: + +1. Open a non-secret flag in Reflag. +2. Select **Settings**. +3. Open the **Opt-in** section. +4. Enable **End-user opt-in**. +5. Optionally enter a **Public description**. +6. Save your changes. + +The public description is exposed through Reflag's client-side SDKs. You can display it in your product's opt-in interface to explain the feature to your users. + +
Opt-in settings with end-user opt-in enabled and a public description

Enable end-user opt-in and optionally add a public description.

+ +{% hint style="info" %} +End-user opt-in cannot be enabled for secret flags. Opt-ins are submitted directly from a browser or client using a publishable key, so the flag must be publicly available. +{% endhint %} + +Opt-in is enabled at the flag level, but access is configured separately for each environment. In every environment where users should be able to opt in, ensure that **Access** is set to **Some**, rather than **No one**. + +When you enable opt-in while the current environment is set to **No one**, Reflag changes its access setting to **Some**. + +## User and company opt-ins + +Your opt-in interface can let end users opt in at either of two scopes: + +* **User opt-in** gives access to one user. +* **Company opt-in** gives access to users evaluated as members of that company. + +The scope depends on how you build your opt-in interface. For example, a personal beta-preferences page might use user opt-ins, while an organization settings page might let an administrator opt in the entire company. + +User and company opt-ins are independent. A user can be opted in personally, through their company, or through both scopes. Removing one membership does not remove the other. + +## View opted-in users and companies + +After enabling end-user opt-in, an **Opt-ins** tab appears next to the flag's **Access** tab. + +As end users opt in, their memberships appear in two places: + +* The **Access** tab shows opted-in users and companies as a separate, read-only access path alongside your regular access rules. +* The **Opt-ins** tab provides an editable list for the selected environment. + +The **Access** tab helps you understand the flag's effective audience. Opt-in membership is combined with your other access rules using **OR**, so an opted-in user or company can receive access without matching another rule. + +## Manage opt-ins + +Use the **Opt-ins** tab to add or remove opted-in users and companies manually. + +You can select known users or companies individually. To add a larger audience, open the user or company selector, choose **Import**, and paste IDs separated by commas, spaces, or line breaks. + +
The Opt-ins tab for managing opted-in companies and users

View and manage company and user opt-ins for the selected environment.

+ +Membership changes apply only to the currently selected environment. + +## Disable end-user opt-in + +Disabling end-user opt-in: + +* Prevents new opt-ins from being added. +* Makes existing memberships inactive, so they no longer grant access. +* Retains existing memberships instead of deleting them. +* Still allows existing memberships to be removed from the **Opt-ins** tab. + +If you enable opt-in again, retained memberships become active again as long as the environment's access setting is not **No one**. + +## Build an opt-in interface + +Reflag does not impose a particular end-user experience. You can build a Labs page, beta settings page, organization-level experiments page, or any other interface that fits your product. + +See [Beta feature opt-in](../guides/self-opt-in.md) for a step-by-step React implementation using Reflag's SDK hooks.