Regional rules and geo-targeting

Regional rules let one banner behave differently depending on where the visitor is. A typical setup shows an opt-in banner to EU visitors, an opt-out banner to California, and nothing at all where no rule applies.

You manage rules on the banner's Regional settings page: Dashboard → Banners → your banner → Regional settings. If automatic or disabled mode is active, click Customize rules to begin. After changing rules, click Save Settings on that page, then Publish from the banner header — rule changes only reach visitors on publish.

How a visitor is matched

The CDN edge determines the visitor's country and region and passes them to the banner script. The matcher in the runtime then evaluates your rules:

1. Rules are checked against the visitor's country (ISO code, case-insensitive). A rule can also name specific regions (for example US states) and excluded regions.
2. A rule that names regions only matches when the visitor's region matches one of them; a rule without regions matches the whole country.
3. Region-exact matches win over country-only matches. Within the same tier, the rule with the highest priority number wins; ties go to the rule defined first.
4. If no rule matches — or the visitor's country could not be determined — the fallback settings apply. By default the fallback shows the banner in opt-in mode; you can configure it to hide the banner instead.

A regional rule controls:

• Whether the banner shows (showBanner). Hiding the banner has a serious consent consequence — read the next section before using it.
• Consent mode — optIn (nothing non-necessary until the visitor accepts), optOut (categories pre-activated until the visitor opts out), or notice (informational).
• Consent Mode defaults and default categories for that region — these shape Google Consent Mode signal states only. They do not limit what a hidden banner grants (see below).
• Translation and layout overrides for that region.
• Privacy-signal behavior for that region (see Privacy signals).

The same matcher runs in the full banner runtime and in the lightweight CDN loader. The CDN copy is a generated ES5 twin of the canonical matcher, and a parity test keeps the two implementations in lockstep, so a rule you test in preview behaves identically at the edge.

Hiding the banner auto-grants every configured category

When a rule (or the fallback) hides the banner and the visitor has no stored consent yet, the runtime does not apply a limited set of categories — it records acceptance of every category in your banner configuration, as if the visitor had clicked "Accept all". Specifically, the write is:

• every configured category, recorded with acceptType: 'all';
• marked as a machine-written default (isDefaultState: true, collectedVia: 'hidden_autogrant'), so it is not counted as the visitor's first consent and does not log a consent_given event;
• skipped entirely when the visitor already has a valid stored consent — an existing choice is never overwritten by a hidden rule.

Because every category is granted, every category-gated tag is released for that visitor. Do not hide the banner in a region expecting only some categories (or only Consent Mode defaults) to be granted — that limited-grant behavior does not exist. The rule's Consent Mode defaults and defaultCategories are a separate mechanism that derives Google Consent Mode signal states such as ad_storage and analytics_storage. CookieBeam derives pre-decision resource activation from the effective consent mode and the banner categories' enabled and readOnly flags instead. Neither mechanism narrows the hidden-banner grant.

Two experiment guardrails can block the auto-grant: an applied experiment override that resolves to opt-in or notice, or a regional experiment override on an opt-in baseline. In either case, the hidden branch returns without granting categories and without mounting the banner. The guardrail does not make the visitor see the banner.

There is no built-in way to silently grant only a subset of categories. If a region should get strictly-necessary storage without a consent prompt, the honest configuration is an opt-in banner the visitor can dismiss: a visitor who never chooses stays pending with only readOnly (necessary) categories active. Hiding the banner always means granting everything.

Legal-framework presets

CookieBeam ships preset rules for common frameworks — GDPR (EU/EEA), UK GDPR, CCPA/CPRA (California), the other US opt-out states, LGPD (Brazil), PIPEDA (Canada), and more. Applying a preset creates a rule pre-filled with that framework's regions, consent mode, banner text, and layout — for example, the GDPR preset covers the EU/EEA countries with an opt-in banner, while the CCPA preset covers California with an opt-out banner and a US opt-out preferences panel.

Treat presets as starting points, not legal advice. They encode reasonable defaults for review with your own counsel; you can adjust every field of the resulting rule.

When you create a rule from a preset, the preset's text and layout are copied into the rule at creation time. Afterwards the rule is self-contained: later edits to the preset do not rewrite existing rules, and your per-rule customizations always win over the preset values.

Precedence summary

For banner text and layout, the effective result for a matched visitor is:

1. your base banner translation and layout,
2. overridden by the framework preset captured in the rule,
3. overridden by your per-rule customizations.

For rule selection itself: region-exact match, then country-only match, then fallback — priority order breaking ties at each step.

Verify a rule end to end

1. On the Regional settings page, click Customize rules if it is shown, add your rule (or apply a preset), set its regions, consent mode, and visibility, and click Save Settings.
2. Click Publish in the banner header so the new rules compile into the served bundle.
3. Open your site in a clean browser profile (no stored consent) from the target region — or use your CDN edge's geo-override / the banner preview with a simulated region — and confirm: the right banner variant shows (or doesn't), and the consent record it writes carries the expected categories and collectedVia provenance.
4. If behavior looks stale, re-check that you published after saving; the edge cache serves the last published bundle, not the saved draft.