Title: Core Concepts
Locale: en
URL: https://sensorswave.com/en/docs/feature-gates/core-concepts/
Description: Deep-dive into how Feature Gates work and their core concepts
This article introduces the core concepts of Feature Gates to help you understand how they work and use and manage them more effectively.

## Basic structure of a Feature Gate

A complete Feature Gate contains the following core elements:

### Gate identifier

Each Feature Gate has a unique identifier used to reference it in code:

- **Key**: The identifier used in code, for example `new_recommendation_algorithm`
- **Display Name**: The user-friendly name shown in the console, for example "New Recommendation Algorithm"
- **Description**: Explains the purpose and background of the Feature Gate

### Default value

The value returned when a user doesn't match any rule:

- **Default value is `false` (disabled)**
- **Fallback guarantee**: When the SDK can't connect to the server, it also returns the default value `false`

> **Note**: The default value for a Feature Gate is `false` (disabled). Rules are used to progressively enable it.

### Targeting rules

Targeting rules determine which users can see the Feature Gate. See the [Targeting rules](#targeting-rules) section below.

## Targeting rules

Targeting rules determine which users can see the Feature Gate. Sensors Wave supports multiple rule types that you can combine.

### Rule types

#### 1. Universal rule (all users)

A rule that applies to all users. Use this for full rollouts or full disablement.

**Example**:
```javascript
// Rule config: all users pass
const hasFeature = await SensorsWave.checkFeatureGate('global_feature');
// Returns: true
```

#### 2. Property rule (system-defined properties)

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

**Supported properties**: App Version, Browser Name, Browser Version, Device Model, IP Address, Operating System, Country, Province, $city, and more.

**Supported conditions**:
- **Equals**: `App Version` equals `2.0.0`
- **Not equals**: `Country` not equals `CN`
- **Contains**: `Browser Name` contains `Chrome`
- **Greater than / Less than**: `App Version` is greater than or equal to `2.0.0`

**Example**:
```javascript
// Rule config: App Version >= 2.0.0
const hasFeature = await SensorsWave.checkFeatureGate('new_version_feature');
// Returns: true (if the user's App Version >= 2.0.0)
```

#### 3. Subject ID rule

Matches users precisely by user ID (Login ID or Anonymous ID).

**Use cases**:
- Internal test users
- Custom experiences for specific customers
- Quick issue validation

**Example**:
```javascript
// Rule config: user ID is in the specified list
const hasFeature = await SensorsWave.checkFeatureGate('test_feature');
```

#### 4. Custom rule (custom properties)

Determines eligibility based on custom user properties. You can configure conditions and Allocation percentages flexibly.

**Use cases**:
- Target users by custom business properties
- Flexible gradual rollout

**Example**:
```javascript
// Rule config: custom property user_level = "VIP", 100% Allocation
const hasFeature = await SensorsWave.checkFeatureGate('vip_feature');
// Returns: true (if the user's user_level is VIP)
```

#### 5. Gates rule

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

| Rule type | Description |
|-----------|-------------|
| **Passes Target Gate** | Matches when the user passes the target gate |
| **Fails Target Gate** | Matches when the user fails the target gate |

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

**Example**:
```javascript
// Rule config: enable advanced_feature when user passes base_feature gate
const hasFeature = await SensorsWave.checkFeatureGate('advanced_feature');
```

### Allocation configuration

Each rule requires an Allocation percentage, which determines what fraction of users who meet the condition pass the gate:

| Configuration | Effect |
|---------------|--------|
| Pass 100%, Fail 0% | All users who meet the condition pass |
| Pass 50%, Fail 50% | A random 50% of users who meet the condition pass |
| Pass 10%, Fail 90% | A random 10% of users who meet the condition pass (gradual rollout) |

> **Note**: Allocation is based on user ID hashing, so the same user always gets the same result.

### Combining rules

Multiple rules can be combined for more flexible control.

#### Rule priority

Rules are evaluated top to bottom. Once a rule matches, its value is returned immediately — no further rules are evaluated.

**Example configuration**:

| Priority | Rule name | Condition | Return value |
|----------|-----------|-----------|--------------|
| 1 | Internal test users | Subject ID matches | Enabled |
| 2 | VIP users | Custom property `user_level` = `VIP` | Enabled |
| 3 | 10% gradual rollout | Universal rule, 10% Allocation | Enabled |
| — | Default | — | Disabled |

**Matching flow**:

```
User A: Subject ID is in the test list, user_level = VIP
→ Matches rule 1, returns: Enabled

User B: Subject ID is not in the list, user_level = VIP
→ Skips rule 1, matches rule 2, returns: Enabled

User C: Subject ID is not in the list, user_level = Basic
→ Skips rules 1 and 2, enters rule 3 percentage evaluation
→ If within the 10% range, returns: Enabled; otherwise continues

User D: Doesn't match any rule
→ Returns default value: Disabled
```

#### Rule order recommendations

1. **Subject ID rules**: Internal testing, specific users — place first
2. **Property rules / Custom rules**: Precision targeting rules
3. **Universal rules (gradual rollout)**: General rollout — place last
4. **Default value**: Fallback, returns `false`

> **Best practice**: Put special rules first and general rules last to ensure priority users match first.

## Gate status

Feature Gates have 5 possible statuses:

| Status | Description |
|--------|-------------|
| **Draft** | Gate has been created but not published — has no effect on users |
| **Debugging** | Gate is in debug mode for internal testing |
| **Running** | Gate is published and active |
| **Released** | Gate has completed its release process; feature runs stably |
| **Finished** | Gate lifecycle has ended; feature is fully launched or retired |

### Status transition flow

```
Draft → Debugging → Running → Released → Finished
```

## How the SDK works

Understanding how the SDK works helps you use Feature Gates more effectively.

### Configuration fetch and cache

1. **On app startup**: The SDK fetches the Feature Gate configuration from the server
2. **Local cache**: Configuration is stored locally; subsequent checks read from cache
3. **Periodic updates**: The SDK checks for configuration updates every 10 minutes

### Degradation strategy

When the SDK can't connect to the server:

1. Use the locally cached configuration (if available)
2. If there's no cache, return the default value `false`

```javascript
// Check Feature Gate — returns false as fallback
const hasFeature = await SensorsWave.checkFeatureGate('new_feature');
```

### Performance optimization

- **Local cache**: Avoids requesting the server on every check
- **Async updates**: Configuration updates don't block the main flow
- **Lightweight evaluation**: Rule matching happens locally — millisecond-level response

## Next steps

Now that you understand the core concepts of Feature Gates, you can:

1. **[Create and Configure](create-and-configure.mdx)**: Learn how to create and configure Feature Gates
2. **[SDK Integration](sdk-integration.mdx)**: Learn how to use Feature Gates in code

---

**Last updated**: January 28, 2026