Chain Signals and Prefetch

Use this guide to understand how chain signals, rule evaluation, and prefetch work together to enable cross-event personalization.

When to use

• You want to personalize a visitor's experience based on their behavioral history across multiple page views.
• You need to understand how signal-based rules differ from static routing rules.
• You are integrating the chain signals API to drive dynamic content decisions.

Concept overview

Chain signals extend the platform's personalization beyond single-click routing. Instead of deciding the redirect destination at click time only, chain signals let you:

1. Collect behavioral signals as a visitor interacts with your content.
2. Accumulate a behavioral profile in a time-windowed signal ledger.
3. Evaluate rules that react to accumulated signals rather than just current-click context.
4. Prefetch decisions for multiple trigger events in a single request.

This enables scenarios like: "If the visitor viewed the pricing page and spent 30 seconds on the features page, show the enterprise CTA on their next visit."

Signal model

A signal is a discrete behavioral observation about a visitor within a session:

Signals are stored in the Signal Ledger — an append-only, time-windowed DynamoDB table with automatic TTL cleanup.

Session identity

All signals within a session share a sessionId with the format:

sig_{handle}_{timestamp}_{randomId}

A session can accumulate up to 200 signals. Signal write rate is limited to 60 signals per session per minute (120 per IP per minute for public endpoints).

Consent and retention

Chain rules

A chain rule defines when accumulated signals should trigger an action. Rules are evaluated in priority order (lower number = higher priority), and the first match wins.

Rule structure

{
  "ruleId": "early-bird-expired",
  "enabled": true,
  "priority": 100,
  "triggerEvent": "early_bird_deadline",
  "when": {
    "countryIn": ["US", "GB"],
    "deviceIn": ["MOBILE", "DESKTOP"]
  },
  "chainConditions": {
    "require": [
      { "signalKey": "early.bird.deadline", "operator": "equals", "signalValue": "expired" }
    ],
    "exclude": [
      { "signalKey": "already_purchased", "operator": "exists" }
    ],
    "minChainDepth": 1,
    "maxChainAgeMinutes": 1440
  },
  "action": {
    "type": "redirect",
    "destinationUrl": "https://example.com/regular-pricing"
  }
}

Condition operators

Window scoping

Conditions can optionally be scoped:

Chain constraints

Rule evaluation flow

1. Load all enabled rules for handle + triggerEvent
2. Sort by priority (ascending), then by ruleId
3. For each rule:
   a. Check basic conditions (device, country, source, campaign)
   b. Check chain depth constraint
   c. Check chain age constraint
   d. Evaluate ALL "require" conditions (must all match)
   e. Evaluate ALL "exclude" conditions (must all NOT match)
   f. First rule where all checks pass → return its action
4. If no rule matches → return { matched: false }

Action types

When a rule matches, it returns an action for the client to execute:

Actions support variable interpolation: signal values can be inserted into action fields using {{signalKey}} syntax.

Prefetch

Prefetch lets you pre-compute decisions for multiple trigger events in a single request. This eliminates round-trips when the client needs to know what to do for several possible events.

POST /v2/public/chain/prefetch

{
  "handle": "myhandle",
  "sessionId": "sig_myhandle_1234_abc",
  "triggerEvents": ["exit_intent", "idle_30s", "add_to_cart"],
  "currentContext": {
    "device": "mobile",
    "country": "US",
    "source": "email",
    "pageUrl": "https://example.com/product"
  }
}

Response:

{
  "decisions": {
    "exit_intent": { "matched": true, "ruleId": "offer_popup", "action": { ... } },
    "idle_30s": { "matched": false, "ruleId": null, "action": null },
    "add_to_cart": { "matched": true, "ruleId": "cross_sell", "action": { ... } }
  },
  "validUntil": "2026-02-25T12:35:56.789Z"
}

Prefetch results are cached server-side for 60 seconds per session + trigger event + context hash. Up to 10 trigger events per prefetch request.

Segment token flow

When signals include segment hints (via metadata.intentSegments), the server:

1. Validates segment labels (regex: ^[a-z0-9][a-z0-9_-]{0,29}$, max 5 segments).
2. Signs them into an HMAC token.
3. Returns a segmentToken in the response.
4. The client stores the token as the lp_seg cookie.

This token is then available to personalization rules that use segmentIn conditions during redirects.

Required auth

Public endpoints (no auth required)

Handle-scoped endpoints (JWT or PAT)

Limits

Common errors

Related:

• Context Token Lifecycle
• Smart Link Personalization
• Vector Embedding Targeting
• Glossary