> For the complete documentation index, see [llms.txt](https://documentation.freshpaint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.freshpaint.io/integrations/consent-management/freshpaint-consent-manager/targeted-consent-configurations.md).
# Targeted Consent Configurations
Freshpaint Consent Manager supports targeted consent configurations, which allow different consent behaviors based on a visitor's geographic location or the domain being visited. This enables compliance with region-specific privacy regulations without requiring separate Freshpaint environments for each region.
Targeting operates in one of three modes: **Disabled**, **Managed**, or **Custom**. Each mode determines how the consent modal, consent model, and category settings are applied to visitors in different locations.
{% hint style="info" %}
Targeting is configured per environment. Changes are saved automatically as a draft but are not live until published. See Publishing Changes for details.
{% endhint %}
### Geotargeting Modes
#### Disabled
When targeting is set to **Disabled**, no location-based logic is applied. The base consent configuration applies to all visitors regardless of their geographic location. This is the default mode.
#### Managed
When targeting is set to **Managed**, Freshpaint automatically applies stricter consent settings to visitors located in regulated regions. The following changes are enforced for visitors in managed regions:
* The consent model is forced to **opt-in**, regardless of the base configuration
* All non-essential consent categories become read-only (visitors cannot enable them without explicit consent)
* GDPR-style consent copy is displayed in the consent modal
Visitors outside managed regions continue to receive the base consent configuration.
**Managed Mode Regions**
Managed mode covers two groups of regulated regions:
**United States : States with Digital Privacy Laws**
| State | Code |
| ------------- | ------- |
| California | `US-CA` |
| Colorado | `US-CO` |
| Connecticut | `US-CT` |
| Delaware | `US-DE` |
| Iowa | `US-IA` |
| Maryland | `US-MD` |
| Minnesota | `US-MN` |
| Montana | `US-MT` |
| Nebraska | `US-NE` |
| New Hampshire | `US-NH` |
| New Jersey | `US-NJ` |
| Oregon | `US-OR` |
| Tennessee | `US-TN` |
| Texas | `US-TX` |
| Utah | `US-UT` |
| Virginia | `US-VA` |
**GDPR Regions**
All 27 EU member states, the United Kingdom, EEA countries (Iceland, Liechtenstein, Norway), European microstates (Andorra, Monaco, San Marino, Vatican City), and French, Dutch, and Danish overseas territories are included.
| Region Group | Examples |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| EU Member States | `DE`, `FR`, `IT`, `ES`, `NL`, `PL`, `SE`, `AT`, `BE`, `BG`, `HR`, `CY`, `CZ`, `DK`, `EE`, `FI`, `GR`, `HU`, `IE`, `LV`, `LT`, `LU`, `MT`, `PT`, `RO`, `SK`, `SI` |
| United Kingdom | `GB` |
| EEA Countries | `IS`, `LI`, `NO` |
| Microstates | `AD`, `MC`, `SM`, `VA` |
| Overseas Territories | French, Dutch, and Danish overseas territories |
{% hint style="warning" %}
The list of managed regions is maintained by Freshpaint and may be updated as new privacy laws take effect. Contact with questions about specific region coverage.
{% endhint %}
#### Custom
When targeting is set to **Custom**, the configuration supports one or more custom configurations. Each custom configuration defines a set of match conditions and the consent settings to apply when all conditions are met.
Custom mode provides full control over:
* Which regions or domains trigger a specific configuration
* The consent model (opt-in or opt-out) for each configuration
* Custom consent modal copy and display settings per configuration
* The ability to skip consent management entirely for matching visitors
### Custom Configurations
Custom configurations are available only in **Custom** mode. Each custom configuration consists of a label, one or more match conditions, and consent settings that override the base configuration when matched.
#### Match Conditions
Each custom configuration contains one or more match conditions. All conditions must match for the configuration to apply (AND logic).
Two types of match conditions are available:
**Region**
Region conditions match based on the visitor's geographic location. Region codes follow the ISO 3166 format:
* Country-level: Use the ISO 3166-1 alpha-2 country code (for example, `DE` for Germany, `FR` for France, `CA` for Canada)
* Country and subdivision: Use the format `COUNTRY-REGION` (for example, `US-CA` for California, `US-NY` for New York)
Multiple region codes can be included in a single region condition. If the visitor's location matches any one of the listed region codes, the region condition is satisfied.
**Domain**
Domain conditions match based on the current page URL. Each pattern is a JavaScript regular expression tested against `window.location.href`.
* Patterns are regular expressions, not glob patterns
* Example: `.*staging\.example\.com.*` matches any URL containing `staging.example.com`
* Multiple patterns can be included in a single domain condition. If any pattern matches, the domain condition is satisfied
* An invalid regular expression silently fails and does not match
{% hint style="info" %}
When combining region and domain conditions in the same custom configuration, both must match for the configuration to apply. For example, a configuration with a region condition of `US-CA` and a domain condition of `.*production\.example\.com.*` only applies to visitors in California who are on a URL matching that pattern.
{% endhint %}
#### Custom Configuration Settings
Each custom configuration can override the following settings from the base configuration:
| Setting | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Consent Model** | Set to **opt-in** or **opt-out** for matching visitors |
| **Consent Modal Copy** | Override the text displayed in the consent modal |
| **Display Settings** | Override display behavior such as auto-showing the consent modal |
| **Skip Consent Management** | When enabled, the consent manager does not initialize for matching visitors. No modal is shown, no cookies are set, and no consent events are sent. |
If a custom configuration does not specify custom modal copy or display settings, the values from the base configuration are used as a fallback.
#### Evaluation Order
Custom configurations are evaluated in the order they appear in the configuration list. The first custom configuration whose match conditions are all satisfied is applied. Remaining configurations are not evaluated.
If no custom configuration matches, the base configuration applies.
{% hint style="warning" %}
When multiple custom configurations have overlapping region or domain conditions, the order matters. The first match wins. Reorder configurations in the Freshpaint Consent Manager interface to control priority.
{% endhint %}
### Skip Consent Management
The **Skip Consent Management** option is available within custom configurations. When a matching custom configuration has this option enabled:
* The consent manager does not initialize
* No consent modal is shown to the visitor
* No consent cookies are set
* No consent events are sent
Common use cases for skipping consent management include:
* Staging or development environments where consent is not needed
* Internal testing domains
* Regions where consent collection is not required by applicable law
To configure this, create a custom configuration with the appropriate domain or region conditions and enable the **Skip Consent Management** toggle.
### How Geolocation Works
When the Freshpaint JavaScript Snippet loads on a page, it calls the `/geolocation` endpoint to determine the visitor's location. This endpoint returns the visitor's country and region based on IP address (resolved via CloudFront headers).
The SDK then evaluates the visitor's location against the configured targeting policies to determine which consent configuration to apply.
**Fallback behavior:** If the geolocation request fails (due to network issues or other errors), the base consent configuration applies. No targeted overrides are used.
#### Testing with Geolocation Override
To test targeted configurations without physically being in the target region, set a `geolocation_override` value in the browser's local storage.
1. Open the browser developer tools
2. Navigate to the **Application** tab (Chrome) or **Storage** tab (Firefox)
3. Under **Local Storage**, select the site domain
4. Add a new entry:
* **Key:** `geolocation_override`
* **Value:** A region code such as `US-CA` or `DE`
5. Reload the page
The Freshpaint SDK will use the override value instead of the actual geolocation result. Remove the `geolocation_override` entry and reload the page to return to normal behavior.
{% hint style="warning" %}
The `geolocation_override` is intended for testing only. It is set in the visitor's browser and does not affect other visitors or production behavior.
{% endhint %}
### Interaction with Global Privacy Control (GPC)
When a visitor has Global Privacy Control (GPC) enabled in their browser and is located in the United States, Freshpaint forces the consent model to opt-in with all non-essential categories disabled (read-only). A GPC notice is added to the consent modal.
This behavior applies regardless of the targeting mode (Disabled, Managed, or Custom). GPC enforcement takes priority over targeting settings for visitors in the United States.
For full details on GPC behavior, see Global Privacy Control (GPC).
### Publishing Changes
All changes to targeting configurations are automatically saved as a draft. Draft changes are not served to visitors.
To make changes live:
1. Navigate to Freshpaint Consent Manager in the Freshpaint account
2. Click **Publish**
1. Optionally enter a description for the published version, and specify if visitors should be prompted for new consent as a result of these changes.
2. Click **Confirm**
Publishing creates a timestamped version, increments the revision number, builds and uploads the consent modal stylesheet to the CDN, and creates a new draft for future edits. Only published versions will appear in the production copy of the Freshpaint Consent Manager.
### Event Queuing with Targeted Configurations
When a targeted custom configuration applies an opt-in consent model, event queuing behaves the same as the base opt-in consent model:
* Events are queued in the browser's local storage while consent is pending
* Queued events are sent with updated consent status once the visitor makes a consent selection
* If the visitor does not interact with the consent modal, the queued events are sent with all non-essential integrations set to `false`
For more details on opt-in event queuing behavior and its limitations, see Consent Management.
### Troubleshooting
**The consent modal does not change for visitors in a managed or custom region**
* Verify that targeting is not set to **Disabled**
* Confirm that the configuration has been published (draft changes are not live)
* Check that the visitor's location matches a configured region by using the `geolocation_override` in local storage to simulate the region
* Clear the browser cache and consent cookies, then reload the page
**A custom configuration does not match expected visitors**
* Confirm that all match conditions use AND logic. Every condition in the custom configuration must be satisfied
* Verify that region codes are in the correct format (`US-CA`, not `California` or `CA` alone for US states)
* For domain conditions, test the regular expression pattern against the full page URL (`window.location.href`), not just the hostname
* Check for invalid regular expression syntax, which silently fails without matching
**Visitors see the base configuration instead of a custom configuration**
* Custom configurations are evaluated in order. The first matching configuration wins. Verify that a more general configuration is not listed before the intended one
* If no custom configurations exist in Custom mode, the base configuration applies by default
**The geolocation override does not work**
* Ensure the key is exactly `geolocation_override` (with underscore) in local storage
* The value must be a valid region code (for example, `US-CA` or `DE`)
* Reload the page after setting the override
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://documentation.freshpaint.io/integrations/consent-management/freshpaint-consent-manager/targeted-consent-configurations.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.