Skip to content

Context Management

Jump to bottom
Kasun Ranasinghe edited this page Sep 8, 2025 · 1 revision

Context Management Guide

This guide covers the context management system in the Flux Gate, which enables sophisticated feature targeting based on user attributes, device characteristics, and custom criteria.

🎯 Overview

Contexts define the criteria used for feature targeting and rollout decisions. They allow you to control which users see specific features based on attributes like user ID, device type, geographic location, or custom business logic.

🔐 Access Requirements

Context management is available to users with appropriate team access:

  • Team Members: Can manage contexts within their assigned teams
  • Team Admin: Full context management for their teams
  • Admin: System-wide context management

📋 Context Concept

What are Contexts?

Contexts are reusable targeting criteria that define:

  • User Attributes: User ID, email domain, subscription tier
  • Device Properties: Device type, operating system, browser
  • Geographic Data: Country, region, timezone
  • Custom Criteria: Business-specific targeting rules

Context Properties

Each context has:

Property Description
Key Unique identifier for the context (e.g., "user_id", "device_type")
Description Human-readable description of the context
Team Scope Contexts belong to specific teams

📋 Context Management Interface

Accessing Context Management

  1. Navigation: Go to Contexts page
  2. Context Table: View all contexts for your teams
  3. Actions: Create, edit, and delete contexts

Context Table

The contexts table displays:

Column Description
Key Context identifier/key
Description Context description or purpose
Actions Edit and delete options

➕ Creating New Contexts

Context Creation Process

  1. Navigate: Go to Contexts page
  2. Create Button: Click "Create New Context"
  3. Form: Fill out context creation form

Context Creation Form

Field Required Description
Key ✅ Unique context identifier (e.g., "user_id", "device_type")
Description ❌ Optional description of the context usage

Example Contexts

Key: user_id
Description: Target specific users by their unique identifier

Key: device_type
Description: Target users based on device type (mobile, desktop, tablet)

Key: subscription_tier
Description: Target users based on their subscription level

Key: geographic_region
Description: Target users based on geographic location

Creation Steps

  1. Context Key: Enter unique identifier (use snake_case or kebab-case)
  2. Description: Add helpful description for team members
  3. Submit: Create the context
  4. Verification: Context appears in the contexts list

✏️ Editing Contexts

Edit Context Information

  1. Context Table: Find context to edit
  2. Edit Action: Click "Edit" button
  3. Edit Form: Modify context details
  4. Save Changes: Update context information

Editable Fields

  • Key: Update context identifier (use with caution)
  • Description: Modify context description

⚠️ Warning: Changing context keys may affect existing feature configurations using that context.

🔧 Context Usage in Features

Contextual Feature Targeting

Contexts are used in Contextual Features to define targeting criteria:

  1. Feature Creation: Select "CONTEXTUAL" feature type
  2. Stage Configuration: Configure stage criteria using contexts
  3. Context Selection: Choose relevant contexts for targeting
  4. Criteria Definition: Define context key and rollout percentage

Context Criteria Configuration

For each pipeline stage, you can define:

Field Description Example
Context The context to use for targeting "user_id"
Context Key Specific value or pattern to match "premium_users"
Rollout Percentage Percentage of matching users to target 25%

Example Stage Criteria

Context: device_type
Context Key: mobile
Rollout Percentage: 50%

This targets 50% of mobile users

Context: subscription_tier  
Context Key: premium
Rollout Percentage: 100%

This targets 100% of premium subscribers

📊 Common Context Types

User-Based Contexts

Target users based on their attributes:

Context Key Description Example Values
user_id Specific user targeting user_12345, premium_users
email_domain Target by email domain @company.com, @gmail.com
user_role Target by user role admin, member, guest
subscription_tier Target by subscription free, premium, enterprise

Device-Based Contexts

Target based on device characteristics:

Context Key Description Example Values
device_type Device category mobile, desktop, tablet
operating_system OS targeting ios, android, windows
browser Browser targeting chrome, firefox, safari
app_version Application version 1.0.0, >=2.0.0

Geographic Contexts

Target based on location:

Context Key Description Example Values
country Country-based targeting US, UK, CA
region Regional targeting north_america, europe
timezone Timezone targeting PST, EST, UTC
language Language preference en, es, fr

Business Contexts

Custom business logic targeting:

Context Key Description Example Values
customer_segment Customer categorization enterprise, smb, startup
feature_flag Nested feature flags beta_program, early_access
experiment_group A/B testing groups control, variant_a, variant_b
account_age Account tenure new_user, veteran

🎯 Context Strategy Patterns

Progressive Rollout Pattern

Use contexts for gradual feature rollout:

Stage 1: Internal Testing
Context: user_role
Key: internal_user
Rollout: 100%

Stage 2: Beta Users  
Context: subscription_tier
Key: premium
Rollout: 25%

Stage 3: General Availability
Context: user_id
Key: all_users
Rollout: 100%

A/B Testing Pattern

Create contexts for experimentation:

Context: experiment_group
Keys: control, variant_a, variant_b
Usage: Split traffic for feature testing

Geographic Rollout Pattern

Deploy features by region:

Stage 1: North America
Context: region
Key: na
Rollout: 100%

Stage 2: Europe
Context: region  
Key: eu
Rollout: 100%

Stage 3: Global
Context: region
Key: global
Rollout: 100%

🔄 Context Integration

Client-Side Integration

Your application needs to provide context values:

// Example context evaluation
const contextValues = {
  user_id: getCurrentUserId(),
  device_type: getDeviceType(),
  subscription_tier: getUserSubscriptionTier(),
  geographic_region: getUserRegion()
};

// Feature evaluation with contexts
const isFeatureEnabled = evaluateFeature('new-ui-feature', contextValues);

Server-Side Integration

Contexts can be evaluated on the server:

// Server-side context evaluation
const evaluateFeatureForUser = (featureKey, userId) => {
  const userContext = {
    user_id: userId,
    subscription_tier: getUserTier(userId),
    device_type: getRequestDeviceType(),
    country: getRequestCountry()
  };
  
  return featureToggleService.evaluate(featureKey, userContext);
};

🚨 Context Best Practices

Context Design

  1. Descriptive Keys: Use clear, descriptive context keys
  2. Consistent Naming: Follow consistent naming conventions
  3. Team Alignment: Align contexts with team needs
  4. Documentation: Document context usage and expected values

Context Naming Conventions

Use consistent patterns:

# User contexts (prefix: user_)
user_id
user_role  
user_subscription

# Device contexts (prefix: device_)
device_type
device_os
device_browser

# Geographic contexts (prefix: geo_)
geo_country
geo_region
geo_timezone

# Business contexts (prefix: business_)
business_segment
business_tier
business_category

Context Value Patterns

Design consistent value patterns:

# Boolean contexts
is_premium_user: true/false
has_beta_access: true/false

# Categorical contexts  
device_type: mobile|desktop|tablet
subscription_tier: free|premium|enterprise

# Numeric contexts
account_age_days: 0-365+
usage_score: 0-100

🔧 Context Administration

Context Lifecycle Management

  1. Planning: Define contexts based on targeting needs
  2. Creation: Create contexts with clear documentation
  3. Usage: Apply contexts in feature configurations
  4. Monitoring: Track context usage and effectiveness
  5. Cleanup: Remove unused contexts periodically

Context Maintenance

Regular maintenance tasks:

  • Review Usage: Identify unused contexts
  • Update Documentation: Keep context descriptions current
  • Value Validation: Ensure context values remain valid
  • Team Alignment: Verify contexts meet team needs

🚨 Troubleshooting

Common Issues

Cannot Create Context

Error: Context key already exists

Solution: Choose a unique context key within your team.

Context Not Available in Features

Context not showing in feature configuration

Solution: Ensure you're creating a "CONTEXTUAL" feature type and the context belongs to your team.

Context Values Not Matching

Feature not targeting correctly

Solution: Verify context values in your application match the configured context keys.

Context Integration Issues

If contexts aren't working properly:

  1. Check Context Keys: Verify context keys match between UI and application
  2. Validate Values: Ensure context values are provided correctly
  3. Test Scenarios: Test with different context value combinations
  4. Debug Logging: Add logging to see context evaluation

💡 Tips and Recommendations

Context Strategy

  1. Start Simple: Begin with basic user and device contexts
  2. Iterate: Add contexts as targeting needs become clear
  3. Document Usage: Maintain clear documentation of context purposes
  4. Team Coordination: Coordinate context definitions across teams

Integration Planning

  1. Client Integration: Plan how your application will provide context values
  2. Data Sources: Identify where context data comes from
  3. Performance: Consider performance impact of context evaluation
  4. Fallback Strategy: Plan fallback behavior when context data is unavailable

Context Evolution

  1. Monitor Usage: Track which contexts are most/least used
  2. Deprecation Strategy: Plan how to retire unused contexts
  3. Version Management: Consider versioning for context schemas
  4. Migration Planning: Plan context key changes carefully

🔗 Related Documentation

Need help? Check the Troubleshooting guide or create an issue in the project repository.

Clone this wiki locally