Evaluation contexts

Evaluation contexts provide fine-grained control over where and when your feature flags evaluate. By constraining flag evaluation to specific contexts, you can reduce unnecessary evaluations, optimize costs, and better organize your feature management strategy.

What are evaluation contexts?

Evaluation contexts are constraints that determine when a feature flag should be evaluated. They're configured in the PostHog UI in a dedicated Evaluation Contexts section on each feature flag. Evaluation contexts actively filter which flags are returned during evaluation requests.

When you configure evaluation contexts on a feature flag:

The flag only evaluates when the SDK's /flags request provides matching contexts via evaluation_contexts (or a supported legacy evaluation_environments parameter)
Flags without evaluation contexts continue to work as before (evaluating for all requests)
At least one context must match for the flag to be included

Why use evaluation contexts?

1. Application isolation

Prevent feature flags from accidentally affecting the wrong application or context. For example:

Marketing site flags won't affect your main application
Documentation site flags won't impact your mobile apps
Admin panel flags won't evaluate in customer-facing features

2. Cost optimization

Reduce unnecessary flag evaluations and associated costs by:

Only evaluating relevant flags per application context
Reducing network payload sizes
Minimizing server-side processing

3. Better organization

Group and filter flags by their intended application context in the feature flags UI, for example:

Application type (e.g., "main-app", "marketing-site", "docs")
Platform (e.g., "web", "mobile", "api")
Product area (e.g., "checkout", "onboarding", "admin")

4. Improved performance

Smaller, more focused flag sets mean:

Faster evaluation times
Reduced memory usage in SDKs

Setting up evaluation contexts

Step 1: Apply evaluation contexts to flags in the UI

When creating or editing a feature flag:

Navigate to the Evaluation Contexts section on the feature flag page
Add contexts that represent where the flag should evaluate (e.g., "main-app", "marketing-site", "docs", "mobile")

Note: Each flag supports a maximum of 50 evaluation contexts, and each context name can be up to 255 characters.

Remember: Setting evaluation contexts in the PostHog app is only half the setup. Your application needs to declare its context via the SDK configuration (Step 2).

Step 2: Configure your SDKs

This step is essential – after adding evaluation contexts to your flag, you must update a supported SDK configuration to declare which contexts your application represents. The SDK's evaluation context option must match the contexts you've configured in the UI.

Note: Option names vary by SDK. Browser JavaScript uses evaluation_contexts, while Node.js, React Native, Android, iOS, and .NET use evaluationContexts or EvaluationContexts. Some SDKs support legacy evaluation_environments or evaluationEnvironments for backward compatibility – see the SDK support section for version details.

Update your SDK initialization to include evaluation contexts:

posthog.init('YOUR_API_KEY', {
    api_host: 'https://app.posthog.com',
    evaluation_contexts: ['main-app', 'web', 'checkout']
})
const posthog = new PostHog('YOUR_API_KEY', {
    host: 'https://app.posthog.com',
    evaluationContexts: ['main-app', 'api', 'backend']
})
<PostHogProvider 
    apiKey='YOUR_API_KEY'
    options={{
        api_host: 'https://app.posthog.com',
        evaluation_contexts: ['main-app', 'web', 'app']
    }}
>
    <App />
</PostHogProvider>
import PostHog from 'posthog-react-native'

const posthog = new PostHog('YOUR_API_KEY', {
    host: 'https://app.posthog.com',
    evaluationContexts: ['main-app', 'mobile', 'app']
})
import com.posthog.android.PostHogAndroid
import com.posthog.android.PostHogAndroidConfig

val config = PostHogAndroidConfig(
    apiKey = "<ph_project_token>",
    host = "https://us.i.posthog.com"
).apply {
    evaluationContexts = listOf("main-app", "android", "mobile")
}
PostHogAndroid.setup(context, config)
let config = PostHogConfig(
    apiKey: "YOUR_API_KEY",
    host: "https://app.posthog.com"
)
config.evaluationContexts = ["main-app", "ios", "mobile"]
PostHogSDK.shared.setup(config)
var posthog = new PostHogClient(new PostHogOptions
{
    ProjectToken = "YOUR_API_KEY",
    HostUrl = new Uri("https://app.posthog.com"),
    EvaluationContexts = ["main-app", "api", "backend"],
});

How evaluation works

When a flag evaluation request is made:

SDK sends application contexts: The SDK includes its configured evaluation_contexts in the request
PostHog filters flags: Only flags matching these criteria are evaluated:
- Flags with no evaluation contexts (backward compatibility)
- Flags with empty evaluation contexts
- Flags where at least one evaluation context matches the SDK's declared contexts
Results returned: Only the filtered flags are returned to the SDK

Example scenario

Consider these feature flags (with their evaluation contexts configured in the UI):

Flag A: No evaluation contexts → Evaluates for all requests
Flag B: Evaluation contexts ["main-app", "web"] → Only evaluates when SDK declares "main-app" OR "web"
Flag C: Evaluation contexts ["marketing-site"] → Only evaluates when SDK declares "marketing-site"

If an SDK is configured with contexts like evaluation_contexts: ["main-app", "mobile"] or evaluationContexts: ["main-app", "mobile"]:

✅ Flag A evaluates (no constraints)
✅ Flag B evaluates ("main-app" matches)
❌ Flag C does NOT evaluate (no matching application contexts)

Best practices

Start simple

Begin with high-level application distinctions:

main-app vs. marketing-site vs. docs
web vs. mobile vs. api

Use consistent naming

Establish a naming convention for your evaluation contexts:

Application: main-app, marketing-site, docs, admin-panel
Platform: web, ios, android, api
Product area: checkout, onboarding, billing

Document your application contexts

Maintain a list of standard application context names and their purposes to ensure consistent usage across teams.

Gradual adoption

You don't need to add evaluation contexts to all flags at once. Start with new flags or high-traffic flags where the benefits are most significant.

Monitor impact

Track the reduction in flag evaluations and associated cost savings after implementing evaluation contexts.

Differences from evaluation runtime

While both features control where flags evaluate, they serve different purposes:

Feature	Evaluation Contexts	Evaluation Runtime
Purpose	Fine-grained application context constraints	SDK type filtering
Control	User-defined contexts in UI	Predefined options (client/server/all)
Granularity	Unlimited custom contexts	Three fixed options
Configuration	Dedicated Evaluation Contexts section per flag	Per-flag setting
SDK parameter	SDK option, such as `evaluation_contexts`, `evaluationContexts`, or `EvaluationContexts`	Automatic based on SDK type
Use case	Application isolation, cost optimization	Client vs. server separation

For practical examples of using both features together, see How to use evaluation runtimes and contexts together.

Common use cases

Multi-application organizations

If you have multiple applications sharing a PostHog instance:

JavaScript
// Marketing site
posthog.init('KEY', { evaluation_contexts: ['marketing-site', 'web'] })

// Main app
posthog.init('KEY', { evaluation_contexts: ['main-app', 'web'] })

// Documentation
posthog.init('KEY', { evaluation_contexts: ['docs', 'web'] })

Platform-specific features

Separate features by platform while maintaining a single flag source:

iOS SDK contexts: ["main-app", "ios"]
Android SDK contexts: ["main-app", "android"]
JavaScript Web SDK contexts: ["main-app", "web"]

Product area isolation

Separate features by product area within your main application:

JavaScript
// Checkout flow
posthog.init('KEY', { evaluation_contexts: ['main-app', 'checkout'] })

// Onboarding flow
posthog.init('KEY', { evaluation_contexts: ['main-app', 'onboarding'] })

// Admin panel
posthog.init('KEY', { evaluation_contexts: ['admin-panel', 'web'] })

Troubleshooting

Flags not evaluating

If a flag with evaluation contexts isn't evaluating:

Check that your SDK is configured with evaluation contexts – this is the most common issue. Your application must explicitly declare its contexts.
Verify at least one evaluation context in the UI matches your SDK's configured contexts
Ensure the evaluation contexts are configured in the Evaluation Contexts section on the flag
Confirm you've deployed the SDK configuration changes to your application

All flags evaluating

If you're still seeing all flags despite using evaluation contexts:

Confirm your SDK version supports evaluation contexts
Check that flags have evaluation contexts configured in the Evaluation Contexts section (not just tags)
Verify your SDK is sending the evaluation_contexts parameter

Performance not improved

If you don't see performance improvements:

Ensure you've added evaluation contexts to high-traffic flags
Check that your application contexts are specific enough to filter effectively
Monitor the reduction in evaluated flags using PostHog analytics

Migration guide

To adopt evaluation contexts in an existing PostHog setup:

Audit current flags: Identify which flags are used in which application contexts
Define context taxonomy: Create a consistent naming scheme for your contexts
Configure contexts: Add evaluation contexts to your flags in the Evaluation Contexts section
Update high-impact flags first: Start with flags that have the most evaluations
Update SDKs gradually: Roll out SDK changes with evaluation contexts per context
Monitor and adjust: Track the impact and refine your evaluation context strategy

SDK support

Evaluation contexts are supported as first-class SDK configuration in the following SDKs. SDKs not listed here don't currently expose a public evaluation contexts configuration option.

SDK	Current option	Legacy option
JavaScript Web	`evaluation_contexts` in 1.331.0+	`evaluation_environments` in 1.269.0+
React Native	`evaluationContexts` in 4.21.0+	`evaluationEnvironments` in 4.10.0+
Node.js	`evaluationContexts` in 5.23.0+	`evaluationEnvironments` in 5.10.0+
Android	`evaluationContexts` in 3.29.1+	`evaluationEnvironments` in 3.24.0+
iOS	`evaluationContexts` in 3.38.0+	`evaluationEnvironments` in 3.33.0+
.NET	`EvaluationContexts` in `PostHog` 2.8.0+ and `PostHog.AspNetCore` 2.7.0+	Not supported

Note: If you're on an older supported SDK version that only supports the legacy option, that will continue to work. We recommend using the current option for new implementations.