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.

Targeting is configured per environment. Changes are saved automatically as a draft but are not live until published. See Publishing Changes for details.

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

The list of managed regions is maintained by Freshpaint and may be updated as new privacy laws take effect. Contact [e-mail] with questions about specific region coverage.

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

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.

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.

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.

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.

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.

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