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 values are extracted from API requests using headers, query parameters, or configured defaults.

Using Headers (Recommended)

Pass context as x-{key} headers:

curl https://api.foir.io/graphql \
  -H "x-api-key: pk_live_your_key" \
  -H "x-market: uk" \
  -H "x-device: mobile" \
  -H "x-locale: en-GB" \
  -d '{"query": "{ recordByKey(modelKey: \"page\", naturalKey: \"homepage\") { resolved(locale: \"en-GB\") { content } } }"}'

Using Query Parameters

https://api.foir.io/graphql?market=uk&device=mobile&locale=en-GB

Extraction Priority

When the same context is provided in multiple places:

1. Header (x-{key}) — highest priority
2. Query parameter (?{key}=value)
3. Default value — configured fallback

The locale context is also read from the Accept-Language header if no explicit value is provided.

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

Debug Mode

Enable debug mode to see which rules were evaluated, which conditions matched, and why a particular variant was selected.

Via the CLI

Context Dimensions

# List all context dimensions
foir context list
 
# Get a context dimension by ID or key
foir context get <id>
foir context get market
 
# Create a context dimension
foir context create --data '{"key": "market", "name": "Market", "sourceModelKey": "shopify-market"}'
 
# Update a context dimension
foir context update <id> --data '{"name": "Market Region"}'
 
# Delete a context dimension
foir context delete <id>

Via the API

Resolving Content with Context

When resolving content, context values are included in the response so your application knows which variant was served:

query GetPage {
  recordByKey(modelKey: "page", naturalKey: "homepage") {
    id
    resolved {
      content
      resolvedWith {
        locale
        contexts
      }
    }
  }
}

The resolvedWith.contexts field returns the context values that were active during resolution.

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.
• Pass context via headers — headers are cleaner than query parameters for most integrations.
• 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