Scenarios¶

Scenarios are targeting rules that dynamically determine which consent configuration is loaded for a given visitor context. They enable you to serve different consent experiences based on URL patterns, referrer domains, page views, user type, and any custom field value.

What is a scenario?¶

A scenario is a container for an ordered list of rules. Each rule defines:

1. Conditions — what must be true about the visitor's context
2. Target configuration — which consent configuration to load if the conditions match
3. Force banner — whether to show the banner even if the visitor already consented

Every scenario also has a fallback configuration that loads when no rules match.

When to use scenarios¶

Evaluation flow¶

Rules are evaluated in order, top to bottom. The first matching rule determines which configuration loads. If no rule matches, the fallback configuration is used.

flowchart TD
    A["Page loads with Scenario ID"] --> B{"Rule 1 matches?"}
    B -->|Yes| C["Load Rule 1's configuration"]
    B -->|No| D{"Rule 2 matches?"}
    D -->|Yes| E["Load Rule 2's configuration"]
    D -->|No| F{"Rule N matches?"}
    F -->|Yes| G["Load Rule N's configuration"]
    F -->|No| H["Load fallback configuration"]

Rule targeting variables¶

Rules evaluate against a context built from the visitor's current session:

| customField1–customField10 | string | Custom field values from WaulterConfig | "premium", "campaign-summer" |

Supported operators¶

Comparison operators¶

Logical operators¶

Conditions can be combined using logical groups:

Groups can be nested for complex logic:

all:
  - url contains "/shop"
  - any:
    - customField1 equals "vip"
    - pageview > 5

This means: URL contains "/shop" AND (user is VIP OR has more than 5 page views).

Example scenarios¶

Different banner per section¶

A/B test two banner designs¶

Re-consent after purpose changes¶

User-type targeting with custom fields¶

The forceStartCB flag¶

When forceStartCB is enabled on a matched rule, the consent banner is always displayed — even if the visitor has valid, unexpired consent.

Use this for:

• Re-consent flows — when you add new purposes or change legal text, force visitors to re-consent
• Campaign prompts — show a special consent prompt on campaign landing pages regardless of prior consent
• Compliance updates — ensure all visitors see updated consent options after a regulatory change

How it behaves:

1. The visitor's existing consent data is cleared for this page load.
2. The banner opens as if the visitor is new.
3. The visitor must make a new consent decision.
4. The new decision replaces the old one.

Best practices¶

Scenario ordering¶

1. Place re-consent / forceStartCB rules at the top — they override existing consent
2. Place specific targeting rules (campaign pages, user types) in the middle
3. Place broad rules (page sections) lower
4. Let the fallback handle your default / production configuration

Debugging scenarios¶

To verify which rule is matching for a given visitor:

1. Open your site in an incognito window
2. Enable debug: true in WaulterConfig:

   window.WaulterConfig = {
     id: "SC00009",
     useGtm: true,
     debug: true
   };
   

3. Open the browser console and look for Waulter debug output showing which rule matched

Keeping scenarios maintainable¶

• Give rules clear, descriptive names (e.g. "Premium users — branded banner")
• Document the purpose of each scenario in your team's runbook
• Review scenario order after adding new rules — a new rule in the wrong position can override existing ones
• Test changes in GTM Preview mode before publishing