Document end-user opt-in

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)

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 `<ReflagBootstrappedProvider>` without a `<Suspense>` boundary, see the section below. 
+If you're using `<ReflagBootstrappedProvider>` without a `<Suspense>` 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).

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.
+
+<figure><img src="../.gitbook/assets/end-user-opt-in-access.png" alt="The Access tab showing opted-in users and companies as an additional access rule"><figcaption><p>Opt-in membership appears separately from regular access rules and is combined with them using OR.</p></figcaption></figure>
+
+## 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.
+
+<figure><img src="../.gitbook/assets/end-user-opt-in-settings.png" alt="Opt-in settings with end-user opt-in enabled and a public description"><figcaption><p>Enable end-user opt-in and optionally add a public description.</p></figcaption></figure>
+
+{% 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.
+
+<figure><img src="../.gitbook/assets/end-user-opt-in-memberships.png" alt="The Opt-ins tab for managing opted-in companies and users"><figcaption><p>View and manage company and user opt-ins for the selected environment.</p></figcaption></figure>
+
+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.