Feature filters reference
Custom Rollout rules in the Toggly dashboard are stored as filters on each feature definition. The Definitions worker evaluates these filters for client-side SDKs; server-side SDKs evaluate the same filter names in your application process.
Served names: Definitions publish short names — Percentage, Targeting, TimeWindow — for every stack. Use those names in the dashboard and in every SDK. The .NET FeatureProvider maps them to Microsoft.FeatureManagement registration names (Microsoft.Percentage, Microsoft.Targeting, Microsoft.TimeWindow) when evaluating locally.
For a per-SDK map of worker vs local vs fail-closed support, see the SDK × filter matrix.
Combining filters
Each feature has a requirement type:
- Any (default): the feature is enabled if at least one filter passes.
- All: every filter must pass.
Context requirements
| Filter | Client SDK must pass | Worker reads automatically |
|---|---|---|
| Always On | — | — |
| Percentage | identity | — |
| Targeting | identity (+ groups for group rules) | — |
| User Claims | claims map | — |
| Context Property | entity on each eval / widget | — |
| Browser Family, Browser Language, Country, Device Type, Operating System | — (browser fetch) | User-Agent, Accept-Language, CF-IPCountry |
| Time Window | — | Server clock |
Use setContext() on client SDKs to pass identity, groups, and claims.
Always On
Enables the feature for everyone with no additional conditions.
Parameters: none
Example (processed definition):
{ "name": "AlwaysOn", "parameters": {} }
Percentage
Deterministic percentage rollout based on user identity (SHA-256 bucket).
Parameters:
| Name | Type | Description |
|---|---|---|
Value | number | Percentage 0–100 |
Filter name: Percentage
Requires: identity in SDK context (anonymous users do not receive partial rollouts).
Targeting
Target specific users and groups, with optional default rollout percentage for everyone else.
Parameters (after RavenDB index expansion):
| Name | Description |
|---|---|
Audience.Users:0..N | Included user IDs |
Audience.Groups:0..N | Included group names |
Audience.Exclusion.Users:0..N | Excluded users (win over inclusion) |
Audience.Exclusion.Groups:0..N | Excluded groups |
Audience.DefaultRolloutPercentage or Percentage | Rollout % for users not explicitly listed |
IgnoreCase | true by default for user/group matching |
Filter name: Targeting
Time Window
Enable the feature only between start and end datetimes (UTC).
Parameters:
| Name | Type |
|---|---|
Start | ISO 8601 datetime (optional) |
End | ISO 8601 datetime (optional) |
Filter name: TimeWindow
Browser Family
Match the browser family parsed from the request User-Agent.
Parameters:
| Name | Type |
|---|---|
BrowserFamily:0..N | Browser name substring (e.g. Chrome) |
Percentage | Segment rollout gate (0–100) |
Browser Language
Match languages from the Accept-Language header.
Parameters:
| Name | Type |
|---|---|
BrowserLanguage:0..N | Language code substring (e.g. en) |
Percentage | Segment rollout gate |
Country
Match the visitor country from Cloudflare CF-IPCountry (exact match, case-insensitive).
Parameters:
| Name | Type |
|---|---|
Country:0..N | ISO 3166-1 alpha-2 code (e.g. US) |
Percentage | Segment rollout gate |
Device Type
Match device model/family parsed from User-Agent (e.g. iPhone).
Parameters:
| Name | Type |
|---|---|
DeviceType:0..N | Device substring |
Percentage | Segment rollout gate |
Operating System
Match OS family parsed from User-Agent (e.g. Windows, iOS).
Parameters:
| Name | Type |
|---|---|
OperatingSystem:0..N | OS substring |
Percentage | Segment rollout gate |
Filter name: OS
User Claims
Match a claim type and value supplied by the client SDK (same semantics as .NET HasClaim(type, value) on the server).
Parameters:
| Name | Type |
|---|---|
Claim | Claim type / name |
Value | Expected claim value |
Percentage | Segment rollout gate |
Requires: claims in SDK context, e.g. claims: { role: 'admin' } → query ?claim.role=admin (maximum 20 claim types per request).
On client-side SDKs, identity, groups, and claims are sent as query parameters on evaluated-signed. The browser (or any client) can change those values before the request reaches the worker. User Claims on the edge are for rollout targeting and experiments, not for authorization.
- Do not use User Claims alone to gate access to sensitive APIs, admin actions, or protected data.
- Enforce security on your backend with the .NET SDK (or your own server), where claims come from authenticated sessions — not from client-supplied query strings.
- Prefer opaque user IDs for
identityrather than email addresses or other direct identifiers (see Evaluated-signed security).
Context Property
Match a property on the entity instance passed into this evaluation (not the signed-in user). Percentage / rollout never uses entity keys. Context kind lives on the feature (contextKind), not on this filter.
Parameters:
| Name | Type | Description |
|---|---|---|
Property | string | Attribute name on the entity (e.g. Color) |
Operator | string | Comparison: eq, neq, gt, gte, lt, lte, in, contains |
Value | string | Expected value(s); for in, a comma-separated list |
ValueType | string | string, number, datetime, boolean, or string[] |
Filter name: ContextProperty
Requires: entity context on this check or widget. Client SDKs map objects with local registerContext. Server SDKs register kinds at startup (PUT sdk/{appKey}/contexts, opt-out supported). Clients never register schemas.
If the feature value is an EntityGate and you omit entity context, or the kind is unknown, evaluation fails closed (off).
setContext() / identity remains user context for Percentage, Targeting, and User Claims. See Entity & page context.
Related
- SDK × filter matrix — which SDK evaluates each filter (worker vs local vs fail-closed)
- Support floors — canonical runtime minima
- Evaluated-signed responses and evaluation context
- Targeting rules (product guide)
- .NET SDK architecture (server-side filters)