Title: Create and Configure Feature Gates
Locale: en
URL: https://sensorswave.com/en/docs/feature-gates/create-and-configure/
Description: Learn in detail how to create and configure Feature Gates
This article covers how to create and configure Feature Gates in detail, including basic information setup, targeting rule configuration, and more.

## Prerequisites

Before creating a Feature Gate, ensure that:

- You have permission to create Feature Gates
- You understand the [Core Concepts](core-concepts.mdx)
- You've identified the Feature Gate's use case and target users

## Creating a Feature Gate

### Step 1: Go to the creation page

1. Log in to the Sensors Wave console
2. Click **Feature Gates** in the left menu
3. Click the **New Feature Gate** button in the upper right corner

### Step 2: Configure basic information

You must fill in the following required fields when creating a Feature Gate:

#### Name (required)

A user-friendly name displayed in the console, in Chinese or English.

**Examples**:
- New Recommendation Algorithm
- WeChat Pay Switch
- User Profile Redesign

#### Feature Gate Key (required)

The unique identifier used in code.

**Naming conventions**:
- Use lowercase letters, numbers, and underscores
- Use snake_case format
- Use descriptive names that are easy to understand
- Consider adding a module prefix

**Examples**:
- ✅ `recommendation_new_algorithm`
- ✅ `payment_wechat_pay_enabled`
- ✅ `user_profile_redesign`
- ❌ `flag1` (too simple)
- ❌ `NewFeature` (should use lowercase)
- ❌ `test` (not specific enough)

> **Note**: The Feature Gate Key cannot be changed after creation. Choose carefully.

#### Description (required)

A detailed explanation of the Feature Gate's purpose, background, and expected impact.

**Recommended content**:
- Brief description of the feature
- Why this gate is needed
- Expected usage timeline
- Related requirement or task links

**Example**:
```
Deep learning-based product recommendation algorithm, expected to improve
click-through rate by 15%. Used for gradual rollout to verify algorithm
stability and effectiveness. Estimated 2 weeks for rollout, gate to be
removed after full release.
Related requirement: PROJ-1234
```

#### ID type (required)

Select the user identifier type for this Feature Gate:

- **LoginID**: Unique identifier for logged-in users
- **AnonymousID**: Device identifier for non-logged-in users

> **Note**: Most scenarios use LoginID. Use AnonymousID when cross-device tracking or support for non-logged-in users is needed.

### Step 3: Set the default value

The default value is returned when a user doesn't match any rule.

#### Boolean gate

- **Enabled (true)**: Takes effect for all users by default
- **Disabled (false)**: Does not take effect for any user by default

#### Default value recommendations

| Use case | Recommended default | Reason |
|----------|---------------------|--------|
| New feature gradual rollout | Disabled (false) | Enable gradually through rules to control risk |
| Paid feature | Disabled (false) | Not enabled by default; only activate when conditions are met |
| Ops gate | Enabled (true) | Runs normally by default; disable during failures |

> **Note**: The default value also serves as the fallback when the SDK cannot connect to the server.

### Step 4: Save the gate

1. Verify all configurations are correct
2. Click **Save**
3. The gate is created successfully with a **Draft** status

> **Note**: Gates in Draft status will not take effect for users. You must configure rules and publish the gate before it becomes active.

## Configuring targeting rules

Targeting rules determine which users can see the Feature Gate.

### Adding a new rule

1. Go to the Feature Gate detail page
2. Click the **Add New Rule** button
3. Configure rule conditions and return values

### Rule type details

The system supports the following 5 rule types:

1. **Universal** — All users
2. **Property** — System-defined properties (such as App Version, Browser Name, Device Model, IP Address, Operating System, Country, Province, $city, etc.)
3. **Subject ID** — Login ID or Anonymous ID
4. **Custom** — Custom properties
5. **Gates** — Passes Target Gate, Fails Target Gate

#### 1. Property rule

Determines whether to enable a feature based on system-defined or custom properties.

**Configuration steps**:
1. Rule name: Internal test users
2. Select rule type: **Custom** → **Custom property**
3. Enter property key: `is_internal_user`
4. Select condition: **Equals (=)**
5. Enter value: `1` (or `true`)
6. Allocation:
   - **Pass**: `100%` (all users who meet the condition pass)
   - **Fail**: `0%`
7. Click Save

**Notes**:
- Each rule requires an Allocation percentage
- The Allocation percentage determines what fraction of users who meet the condition pass the gate
- `100% pass + 0% fail` = all users who meet the condition pass
- `50% pass + 50% fail` = a random 50% of users who meet the condition pass

**Supported condition operators**:

The system supports the following operators based on the actual available options:

- **=** (Equals): Exact match
- Other operators are automatically provided based on the property type

**Example**:
```
Condition: is_employee = 1
→ Matches users with is_employee property value of 1
```

#### 2. Subject ID rule

Matches users by user ID.

**Configuration steps**:
1. Rule name: Designated test users
2. Select rule type: **Subject ID** → **Login ID** or **Anonymous ID**
3. Enter user IDs that meet the condition
4. Allocation:
   - **Pass**: `100%`
   - **Fail**: `0%`

**Use cases**:
- Internal test users
- Specific customer customization
- Quick issue verification

> **Note**: It's recommended to use custom properties to mark test users rather than directly using ID lists.

#### 3. Percentage gradual rollout rule (Allocation)

Use Allocation percentages to implement gradual rollout.

**Configuration steps**:
1. Rule name: Gradual rollout users
2. Optionally set conditions; without conditions, the rule applies to all users
3. Allocation:
   - **Pass**: Set the pass percentage (for example, 5%)
   - **Fail**: Automatically calculated as the remaining percentage (for example, 95%)
4. Click Save

**Characteristics**:
- Based on user ID hashing, ensuring consistent results for the same user
- User groupings remain relatively stable when the percentage is adjusted
- Ideal for progressive gradual rollout

**Percentage adjustment strategy**:

Gradually increase: 1% → 5% → 10% → 25% → 50% → 100%

> **Note**: When adjusting from 10% to 20%, the original 10% of users remain in the new 20%, ensuring continuity of user experience.

#### 4. Gates rule (depends on another gate)

Uses the result of another Feature Gate to determine the current one.

**Configuration steps**:
1. Rule name: Depends on Gate A
2. Select rule type: **Gates** → **Passes Target Gate** or **Fails Target Gate**
3. Select the target gate
4. Allocation:
   - **Pass**: `100%`
   - **Fail**: `0%`

**Use cases**:
- Dependencies between features
- Combining multiple gates for complex logic
- Phased rollout of related features

**Example**:
```
Gate A: New payment feature
Gate B: New settlement feature (depends on Gate A)

Rule: Passes Target Gate (Gate A), 100% pass Allocation
Meaning: Only users who pass the "New payment feature" gate can see the "New settlement feature"
```

### Override

Override is a special configuration method that lets you quickly enable or disable a feature for specific users **without setting an Allocation percentage**.

**How to use**:
1. Click the **Override** button at the top of the rule configuration area
2. Add or remove user IDs
3. Override users pass directly without going through rule matching

**Use cases**:
- Quickly toggle a feature for internal test users
- Temporarily grant access to specific users
- Quick issue verification

> **Override vs rules**:
> - Override: Directly specify user IDs, automatically passes, no percentage needed
> - Rules: Requires setting conditions and Allocation percentages — more flexible but slightly more complex to configure

### Rule priority and order

#### Rule matching order

Rules are matched from top to bottom. Once the first rule matches, the result is returned immediately without further matching.

**Example**:

| Order | Rule name | Condition | Return value |
|-------|-----------|-----------|--------------|
| 1️⃣ | Internal test users | `is_internal_user` = `1` | Pass |
| 2️⃣ | VIP users | `user_level` = `VIP` | Pass |
| 3️⃣ | 10% rollout | 10% Allocation | Pass |
| — | Default | — | Fail |

#### Adjusting rule order

1. Go to the Feature Gate edit page
2. In the rule list, drag the **drag icon** on the left side of a rule
3. Move to the desired position
4. Click **Save**, then click **Launch**

#### Rule order best practices

**Recommended order** (top to bottom):

1. **Override rules**: Specific users (highest priority)
2. **User property rules**: Internal testing, special users
3. **Subject ID rules**: Designated user IDs
4. **Percentage rollout rules**: General rollout (lowest priority)
5. **Default value**: Fallback

**Principles**:
- Special rules go first
- General rules go last
- Precise matching takes priority over broad matching

### Editing and deleting rules

#### Editing rules

1. Click the **Edit** button on the right side of a rule
2. Modify the rule configuration
3. Click **Save**, then click **Launch**

> **Note**: Rule changes take effect after the SDK updates its cache (within 10 minutes). Proceed with caution.

#### Deleting rules

1. Click the **Delete** button on the right side of a rule
2. Confirm the deletion
3. The rule is immediately deactivated

> **Warning**: Deleting a rule affects users currently matched by that rule. Make sure you understand the impact scope.

## Launching and managing

### Launching the Feature Gate

After configuration is complete, click the **Save** button at the bottom of the page. The Feature Gate takes effect when its status changes to **Running**.

1. Go to the Feature Gate detail page
2. Verify the configuration is correct
3. Click **Save**
4. The Feature Gate status changes to **Running**
5. The SDK updates its cache within 10 minutes and fetches the new configuration

### Viewing gate status

You can see the gate's current status in the Feature Gate list and detail page:

- **Running**: The Feature Gate is active
- Launch time: Shows when the Feature Gate first went live

> **Note**: The SDK uses a periodic polling mechanism (10 minutes) to update configuration, so configuration changes don't take effect instantly.

## Notes

### Naming conventions

- Feature Gate Keys cannot be changed after creation
- Use descriptive names to avoid ambiguity
- Maintain a unified naming convention within the team

### Rule configuration

- Rule changes take effect after the SDK updates its cache (within 10 minutes). Proceed with caution.
- Review rules regularly and clean up unused ones
- Too many rules can affect matching performance; recommended limit is 20 rules

## Next steps

Now that you understand how to create and configure Feature Gates, you can:

1. **[SDK Integration](sdk-integration.mdx)**: Learn how to use Feature Gates in code
2. **[Best Practices](best-practices.mdx)**: Discover the best ways to use Feature Gates

---

**Last updated**: January 28, 2026