Geo Rules

CookieBoss automatically detects visitor location and applies the correct consent behavior based on privacy regulations. With the visual Geo Rules Editor, you can configure region-specific rules in seconds — or go granular with US state-level targeting.

How geo detection works

1. The consent script calls the CookieBoss geo endpoint
2. The endpoint returns the visitor’s country and region (using Cloudflare’s cf-ipcountry header)
3. CookieBoss evaluates your geo rules top-to-bottom and applies the first matching rule
4. The geo result is cached in localStorage for 24 hours

Visual Geo Rules Editor

The easiest way to configure geo rules is through the dashboard’s visual editor.

Accessing the editor

1. Open the CookieBoss dashboard
2. Navigate to Sites and select your site
3. Click the Geo Rules tab

Quick-add region presets

The editor includes 8 built-in presets that cover the most common regulatory regions. Click any preset to instantly add it as a rule:

Creating custom rules

If the presets don’t fit your needs, create custom rules:

1. Click Add Rule
2. Give the rule a name (e.g., “Southeast Asia” or “LGPD Countries”)
3. Select the countries or US states this rule applies to
4. Choose a consent mode:
   • Opt-in — all optional cookies denied by default, visitor must actively consent
   • Opt-out — cookies allowed by default, visitor can opt out
   • Notice — informational banner only, no blocking
5. Toggle Show Banner on or off
6. Drag the rule to set its priority

Rule priority

Rules are evaluated top-to-bottom. The first rule whose region list matches the visitor’s location is applied. If no rules match, the bottom “default” rule is used.

For example, if you have:

1. EEA + UK (opt-in)
2. US Privacy States (opt-out)
3. Rest of World (notice)

A visitor from Germany matches rule 1 and gets opt-in. A visitor from California matches rule 2 and gets opt-out. A visitor from Japan matches rule 3 and gets notice.

US state-level granularity

CookieBoss supports targeting individual US states, which is essential for complying with the patchwork of US state privacy laws:

Use the format US-XX where XX is the two-letter state code. In the visual editor, US states appear in a separate section when you select the United States.

Consent modes explained

Geo rules via API

You can also configure geo rules programmatically. The new format uses a geoRules array where each rule has an ID, name, regions list, consent mode, and banner toggle:

{
"geoRules": [
  {
    "id": "eea",
    "name": "EEA + UK",
    "regions": ["AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","GR","HU","IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE","IS","LI","NO","GB"],
    "mode": "opt-in",
    "showBanner": true
  },
  {
    "id": "us-privacy",
    "name": "US Privacy States",
    "regions": ["US-CA","US-CO","US-CT","US-VA","US-UT","US-TX","US-OR","US-MT"],
    "mode": "opt-out",
    "showBanner": true
  },
  {
    "id": "default",
    "name": "Rest of World",
    "regions": [],
    "mode": "notice",
    "showBanner": false
  }
]
}

Rule object fields

Backward compatibility

The legacy object format with eu, california, and default keys still works:

{
"geoRules": {
  "eu": { "mode": "opt-in", "showBanner": true },
  "california": { "mode": "opt-out", "showBanner": true },
  "default": { "mode": "opt-in", "showBanner": true }
}
}

If you’re already using this format, it will continue to work. However, we recommend migrating to the new array format to take advantage of custom regions and US state-level targeting.

Caching behavior

Geo detection runs once per page view and is kept in memory only. Nothing is written to the visitor’s device before they choose, so the lookup itself never needs consent. This means:

• At most one geo request per page view, and none once the visitor has made a choice
• Visitors on VPNs will be classified based on their VPN exit country
• A reload always re-detects, so there is no cache to clear