Targeting & Context

Targeting rules determine which content variant to show to each visitor. Build rules based on device type, authentication status, geographic market, customer segments, and custom context dimensions you define.

Overview

Foir resolves content variants by evaluating targeting rules against request context. When a visitor requests content:

1. Foir extracts context values (device, market, locale, etc.) from the request
2. Targeting rules are evaluated for each variant in priority order
3. Conditions are checked against the context — “is the user on mobile?”, “is the market UK?”
4. The first matching variant (by priority) is returned
5. If no rules match, the default variant is shown

Key Concepts

• Context dimensions are the values you can target against (device, market, locale, custom dimensions)
• Targeting rules are conditions that compare context values to expected values
• Priority determines evaluation order — higher priority rules are checked first
• First match wins — once a variant’s rules match, evaluation stops

Building Rules

Simple Conditions

A condition compares a context value against a target:

• Device equals mobile
• Market equals UK
• Segment “VIP” is true

Combining Conditions

Use AND/OR to create complex rules:

AND (all must be true):

• Device is mobile AND Market is UK

OR (any can be true):

• Market is UK OR Market is US OR Market is Canada

Nested groups:

• Segment is VIP AND (Device is mobile OR Market is UK)

Available Comparisons

System Contexts

Four built-in contexts are always available without configuration:

auth-status is determined automatically from the customer’s authentication token and cannot be set manually via headers.

Custom Context Dimensions

Custom context dimensions let you target based on your project’s specific needs. Custom contexts are backed by models that provide the list of valid values.

Creating a Custom Context

1. Go to Settings > Context Dimensions
2. Click Create Dimension
3. Configure:
   • Key: unique identifier (e.g., market)
   • Name: display name (e.g., “Market”)
   • Source Model Key: the model that provides values (e.g., shopify-market)
   • Default Value: fallback when no value is provided
4. Click Save

Values come from records in the source model — each record’s natural key becomes a valid context value. For example, a market model with records having natural keys "us", "uk", "eu" provides three valid values for the market context dimension.

Passing Context

Context is passed as the typed contexts argument on any per-model read query (singular or plural). There is no context request header or query parameter — the platform reads targeting context only from this argument.

curl https://api.foir.dev/graphql \
  -H "x-api-key: pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ page(naturalKey: \"homepage\", locale: \"en-GB\", contexts: { device: MOBILE }) { _id title } }"}'

Context dimensions

• device — built-in enum: DESKTOP, MOBILE, TABLET
• platform — built-in enum: WEB, IOS, ANDROID
• locale — BCP-47 string (also accepted as the top-level locale query argument)
• Custom dimensions you configure (e.g. market) appear as additional fields on contexts, typed as an enum of their configured values

auth-status and customer segment membership are not client inputs — the platform derives them server-side from the customer access token.

Defaults

When you omit a dimension from contexts, the platform uses that dimension’s configured default value (set when you create the custom dimension). Built-in dimensions default to DESKTOP / WEB and the project’s default locale.

In the Admin

Creating Targeting Rules

1. Edit a page or record with variants
2. Select a variant
3. Click Targeting Rules
4. Build your rule:
   • Add a condition (e.g., Device equals mobile)
   • Add more conditions and set logic to AND or OR
   • Nest groups for complex rules
5. Set priority (higher = checked first)
6. Save

Managing Context Dimensions

Go to Settings > Context Dimensions to create, edit, or delete custom contexts.

Testing Rules

Preview Panel

1. Open any content with variants
2. Click Preview
3. Use the context selector to simulate different devices, markets, and segments
4. See which variant would display

Via the CLI

The foir context command manages which project and tenant the CLI is pointed at — it does not manage context dimensions. Create, edit, and delete custom context dimensions in the admin app under Settings > Context Dimensions.

# List available projects (current one is marked)
foir context projects
 
# Switch to a different project
foir context switch <projectId>
 
# List available tenants
foir context tenants

Via the API

Resolving Content with Context

Pass contexts on the per-model query; the matching variant’s values come back directly on the typed fields:

query GetPage {
  page(
    naturalKey: "homepage"
    locale: "en-GB"
    contexts: { device: MOBILE }
  ) {
    _id
    title
    hero {
      heading
    }
  }
}

Resolution happens server-side. The public API returns the resolved values on the typed fields — it does not echo back which variant matched or which context values were active.

Best Practices

• Start with device targeting — mobile optimization is usually the first need.
• Always have a default variant — ensure content displays when no rules match.
• Set clear priorities — more specific rules should have higher priority.
• Use descriptive keys — customer-tier is clearer than ctx-1.
• Set default values on custom contexts — ensures content resolves even when no context is provided.
• Keep rules simple — complex rules are harder to maintain and debug.

Common Patterns

Mobile First

Priority 10: Device is mobile  ->  Mobile variant
Priority 0:  Default           ->  Desktop variant

Regional Content

Priority 10: Market is UK  ->  UK variant
Priority 10: Market is US  ->  US variant
Priority 0:  Default       ->  International variant

VIP Experience

Priority 20: Segment includes VIP  ->  VIP variant
Priority 10: Device is mobile      ->  Mobile variant
Priority 0:  Default               ->  Standard variant

Authenticated Users

Priority 10: Auth status is authenticated  ->  Member variant
Priority 0:  Default                       ->  Public variant