---
title: "Regional rules and geo-targeting"
description: "Show different banner behavior per country or region, with rules, priorities, fallbacks, and legal-framework presets."
url: "https://cookiebeam.com/docs/configure/regional-rules"
lang: "en"
---

# Regional rules and geo-targeting

Show different banner behavior per country or region, with rules, priorities, fallbacks, and legal-framework presets.

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](https://cookiebeam.com/docs/configure/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.