How to set up geo-targeting & regional rules

What it is, and why it matters

Not every visitor needs, or legally requires, the same banner behavior. The EU and UK require opt-in consent — nothing beyond strictly necessary cookies fires until the visitor actively agrees. US states with comprehensive privacy laws are effectively opt-out regimes — non-necessary categories run by default, and the visitor's right is to decline afterward. Plenty of jurisdictions require nothing at all. A single banner mode applied globally either over-blocks revenue-driving scripts for visitors who didn't need protecting, or under-protects visitors whose law requires opt-in.

Geo-targeting is how Cookie Munch resolves this without you writing region-detection code yourself: every visitor's region is detected server-side, a default banner mode applies globally, and you layer country-specific overrides on top. The same region signal also drives automatic activation of IAB TCF (EU/EEA/UK only) and GPP/US Privacy (US only), so you don't run frameworks for visitors they don't apply to.

How region is detected

Every request to the embed's config endpoint resolves the visitor's region server-side, in this order:

1. An explicit x-cookiemunch-region header, if your CDN or reverse proxy already sets one.

2. Common CDN geo headers — Cloudflare's cf-ipcountry, Vercel's x-vercel-ip-country (plus its region sub-header, so US traffic resolves to us-ca rather than just us), or a generic x-country header.

3. A bundled, license-free IP→country database as a fallback when no upstream header is present at all — this works out of the box with no MaxMind account or license key. Self-hosted operators who want higher accuracy can point the MAXMIND_DB environment variable at a real MaxMind GeoIP2/GeoLite2 database to override the bundled one.

The resolved region is returned alongside the rest of the config in the same response the embed already fetches to hydrate the banner, so geo rules, TCF/GPP auto-activation, and any region-specific banner design all resolve client-side without a second network round trip.

How to configure rules

1. In Studio, open the site's Settings drawer and go to the Targeting tab (this is a different tab from where you enable Consent Mode/TCF/GPP — Targeting groups language and geo behavior, which are about who sees what, separately from the signaling toggles).

2. Set the Default mode — the banner mode used whenever no rule below matches: opt-in, opt-out, or off.

3. Click Add rule to layer a country-specific override. Each rule has:

   • Countries — a comma-separated list of 2-letter country codes (e.g. de, fr, es).

   • Mode — the mode applied when the visitor's region matches this rule.

4. Add as many rules as you need, then Remove any you no longer want.

5. Publish from Studio.

Rules are evaluated in order, and the first match wins. A country-level rule (e.g. us) also matches state-level subdivisions under it (e.g. a visitor detected as us-ca) by prefix — so a common pattern is to set a broad us rule for your general US default, then rely on the automatic GPC handling (below) for state-specific opt-out behavior rather than trying to enumerate every state as its own rule.

What the three modes actually do

Global Privacy Control and Do Not Track

If a visitor's browser sends Global Privacy Control (navigator.globalPrivacyControl), Cookie Munch forces the effective mode to opt-out and treats it as an explicit decline — this overrides even a matching geo rule that says opt-in or off, because GPC is a legally-recognized opt-out signal in several US states regardless of what your own geo rule says. Concretely: if GPC is present, the banner mode becomes opt-out, but unlike an ordinary opt-out visitor who is implicitly allowed until they decline, a GPC-forced opt-out starts already declined — no non-necessary category runs for that visitor until they affirmatively change it themselves. This mirrors how GPC is expected to feed Consent Mode and GPP opt-outs elsewhere in the product.

Do Not Track (navigator.doNotTrack) is a separate, older signal and is handled differently. The live banner engine reads and exposes DNT on its SDK state for your own use, but does not currently use it to alter banner mode the way it does GPC — DNT was never standardized as a legal opt-out signal the way GPC has been in several US state laws, so treat GPC as the actionable signal and DNT as informational only when you're reasoning about what will actually change a visitor's experience.

Framework auto-activation

Turning on Auto framework by region (found in the IAB TCF section of the Consent tab, since it's shared infrastructure with TCF) has the banner automatically:

• Activate IAB TCF only for visitors whose region resolves to EU/EEA/UK.

• Activate GPP / US Privacy only for visitors whose region resolves to the US.

• Leave everyone else on the plain banner with no regulatory-framework overhead at all — no TC string, no GPP string, nothing to encode or expose for traffic that doesn't need it.

This is the recommended setting for most global sites: it means you configure TCF and GPP once each, and geo-targeting decides who actually gets them, rather than you writing separate region logic for each framework.

Verifying it's working

1. Direct config check. Call your site's /config/:cbid endpoint with a spoofed region header, e.g. curl -H "x-cookiemunch-region: de" https://<your-api-host>/config/<cbid>, and confirm the response's region field and effective banner mode match what you expect. Repeat with us, us-ca, and an unconfigured country to confirm the default falls through correctly.

2. Rule ordering. If you have overlapping rules, spoof the specific case and confirm the first matching rule in your list order is applied, not just any match.

3. GPC test. In a browser with GPC enabled (or a flag/extension that sets navigator.globalPrivacyControl = true), load your site under a region whose rule/default is opt-in or off, and confirm the banner still resolves to an already-declined opt-out state.

4. Framework cross-check. With Auto framework by region on, confirm via __tcfapi('ping', 2, console.log) that TCF is inactive for a non-EU spoofed region and active for an EU one, and likewise with __gpp('ping', ...) for US vs. non-US.

5. Real traffic spot-check. Sample a few consent-log entries in the dashboard's Audit view from visitors in different countries and confirm the recorded region and banner mode line up with your configured rules.

See also: Google Consent Mode v2, IAB TCF v2.2, and US State Privacy (GPP) for how region-based activation feeds each signaling framework.