Segments

Overview

A segment is a reusable set of targeting rules. Segments are useful because they let you define a common audience once and then reuse that audience across many feature flags without duplicating logic. For example, “beta testers,” “premium customers,” or “users in Mexico". A segment is scoped to the project it is created in. Segment rules are based on context properties and can be used across the environments within a project.

Segments make targeting more consistent, reduces the chance of errors, and speeds up rollout changes, since updating a segment instantly updates all feature flags that reference it. Segments are especially valuable for maintaining large-scale feature flag systems where multiple teams work on different features but need to share consistent targeting criteria.

Example Scenarios

Here are some example scenarios where segments would be useful:

1. Beta Testing Programs
   You can create a segment for users who have opted into early access or beta testing. Any feature flag that should be tested by this group can simply reference the “Beta Testers” segment with the appropriate return value. When the membership of that segment changes (new testers join, others leave), all feature flags automatically update without needing manual edits.
2. Geographic Rollouts
   Release a new feature only to users in Canada and Mexico. You can define a “North America (non-US)” segment once, then apply it across multiple feature flags. This makes it easy to roll out region-specific features consistently.
3. Premium or Enterprise Customers
   If your product differentiates between free, premium, and enterprise tiers, you might create a “Premium Customers” segment. That segment can then be reused to unlock advanced features across many parts of the application without repeating the same subscription-level check.
4. Internal Employees
   Many teams test features internally before exposing them to customers. You can define an “Employees” segment that targets all users with company email domains. Any feature under internal testing can be gated behind that segment.

Create a Segment

1. In the Hyphen app, navigate to any project you have at least collaborator access on. Click the Segments tab, then the "Create Segment" button.

2. 

   Give the segment a name.

   Naming Conventions

   Good	Bad	Why
   region-mexico	mx	Descriptive, clear
   plan-premium	pp	Avoids cryptic abbreviations
   role-admins	new-dashboard-testers	Avoids feature tie-in

3. Provide an optional description if the name of the segment is not descriptive enough

4. Click "Create Segment" to create an empty segment.

5. On the segment details page, you'll see:

   • Segment key — reference this in your code
   • Creator — who added the segment
   • Flags — feature flags using this segment
   • Rules — the targeting criteria
   

6. To add a rule, click the "Add Rule". Then click "Add Criteria". You'll see a list of options to create your first rule. Select user.email.

7. Select the in operator for the rules operator and enter a email address(es) separated by commas. Click "Save" to add the rule to the segment.

8. You can continue to add more rules to the segment, but know that rules will be evaluated in the order they appear (top-down) and the first matching rule will result in the evaluation context falling within the segment. If none of the rules are satisfied for a given context, then the segment context will not be in the segment.

Use a segment in a feature flag

To use a segment as a target in a feature flag

1. Create or navigate to an existing feature flag in the same project you've created a segment.

2. Click "Add Target". For the target criteria, select Segment from the dropdown menu.

   

3. Choose in or not in as the operator, and then select your segment.

4. Select the return value of the feature flag if the target criteria is met and click "Save".

You should now see the segment target in the list of feature flag targets.

❗️

Segments that are used by feature flags can not be deleted
A segment that is in use cannot be deleted. If you'd like to delete a segment that is in use, you must first remove the segment from all feature flags that use it.

JSON Logic

Segment rules are written in JSON logic. Once you've created rules in a segment in the Hyphen app, you can access the segment's underlying JSON logic by clicking the "Copy JSON Logic" button next.

Here's an example:

{
  "or": [
    {
      "and": [{ "==": [{ "var": "application" }, "location-app"] }]
    },
    {
      "and": [{ "==": [{ "var": "user.id" }, "1234"] }]
    },
    {
      "and": [
        {
          "in": [
            { "var": "user.email" },
            ["[email protected]", "[email protected]", "[email protected]"]
          ]
        }
      ]
    }
  ]
}

Rules Operator Reference

Best Practices

• Reuse segments across flags, don’t duplicate logic
• Keep rules broad enough to be reused
• Add descriptions when names aren’t self-explanatory

Common Pitfalls

• Overlapping segments that cause conflicting flag rules
• Using feature names in segment names
• Forgetting that editing a segment affects all flags instantly