This article is part of the series Customize your banner for each version of your site. Before following the guide below, make sure you have reviewed the general introduction article Choose the appropriate method to load the correct Axeptio banner.
Geolocation allows you to automatically load the most appropriate configuration based on the visitor's location, determined via their IP address.
This is particularly useful when your site must apply different regulations depending on the country (GDPR, CCPA, Law 25…) and geolocation is a more relevant criterion than language or URL structure.
Geolocation is activated at the project level as a whole. Once activated, it systematically takes precedence over any script targeting (parameter cookiesVersion) or page URL rules, across all sites that load this Axeptio project.
How does it work?
If you have restricted banner visibility to certain countries (see below in this article), this check is performed first: for a visitor located in an unauthorized country, no banner is displayed, regardless of the priority order described below.
When geolocation is enabled, Axeptio selects the configuration to load according to the following priority order:
Subdivision targeting — if one or more configurations directly target the visitor's subdivision (e.g., Quebec, California), they become priority candidates. This targeting is configured at the level of each configuration, independently of geolocation.
Country targeting — if no subdivision targeting applies, and one or more configurations directly target the visitor's country, they become candidates.
Regulation of the visitor's country — if no direct targeting applies, Axeptio detects the visitor's IP address and identifies the regulation associated with their country (e.g., GDPR for a visitor from Spain). All configurations matching this regulation become candidates.
Default configuration (fallback) — if no configuration is a candidate at any of the previous levels, Axeptio loads the default configuration you have defined.
As soon as a level produces multiple candidate configurations, the visitor's browser language determines the outcome: Axeptio selects the one whose language matches; if not, the first candidate configuration is used.
Axeptio uses the visitor's browser language, not the site's language (see scenario 2 below).
The default configuration must be published to be active.
Example
The scenarios below illustrate levels 3 (regulation) and 4 (fallback) of the priority order: none of the configurations in this example directly target a country or subdivision.
Configuration
Published configurations, in this order: GDPR FR, GDPR EN, GDPR ES, GDPR IT, GDPR DE
Default configuration: GDPR FR
None of these 5 configurations directly target a country or subdivision
For scenarios 1 to 5 below, no other regulation (CCPA, Law 25…) is configured on the project. Scenario 6 adds an additional configuration to this base project.
The detected IP does not always correspond to the visitor's actual location: a VPN, corporate proxy, or unrecognized IP can distort this detection (see scenario 5 below).
Scenario 1 — one configuration matches
Variable | Value |
Visitor's actual location | Spain |
Detected IP | Spain |
Regulation associated with this IP | GDPR |
Browser language | Spanish |
Result: the GDPR ES configuration is loaded.
Why:
Axeptio detects a Spanish IP and associates it with GDPR regulation.
All 5 GDPR configurations are candidates.
Since the browser language is Spanish, the GDPR ES configuration is selected among the candidates.
Scenario 2 — the browser is not in the site's language
Variable | Value |
Visitor's actual location | France |
Detected IP | France |
Regulation associated with this IP | GDPR |
Browser language | English |
Result: the GDPR EN configuration is loaded, even on a /fr/ page.
Why:
Axeptio detects a French IP and associates it with GDPR regulation.
All 5 GDPR configurations are candidates.
Since the browser is in English, the GDPR EN configuration is selected among the candidates. The banner follows the browser language, not the URL or the site's displayed language.
Scenario 3 — the regulation does not match any configuration
Variable | Value |
Visitor's actual location | United States |
Detected IP | United States |
Regulation associated with this IP | CCPA |
Browser language | English |
Result: the default configuration, GDPR FR, is loaded.
Why:
Axeptio detects a US IP and associates it with CCPA regulation.
The project contains no CCPA configuration (only GDPR configurations): no configuration is a candidate.
With no candidate configuration, the browser language detection step never occurs.
Scenario 4 — the regulation matches, but no candidate language matches
Variable | Value |
Visitor's actual location | Poland |
Detected IP | Poland |
Regulation associated with this IP | GDPR |
Browser language | Polish |
Result: the GDPR FR configuration is loaded, but not because it is defined as the default banner.
Why:
Axeptio detects a Polish IP and associates it with GDPR regulation.
All 5 GDPR configurations are candidates.
None of these configurations is in Polish: none matches the browser language.
Lacking a language match, Axeptio retains the first candidate configuration in the project's order — here GDPR FR, because it is first in the list of 5 GDPR configurations. The default banner does not come into play at any point in this scenario: it is only used when no configuration shares the visitor's regulation (see scenarios 3 and 5). If GDPR FR had not been the first GDPR configuration in the project, another GDPR banner would have been loaded, even if GDPR FR remained the default banner.
Scenario 5 — a VPN masks the true location
Variable | Value |
Visitor's actual location | France |
Detected IP | United States (VPN active) |
Regulation associated with this IP | CCPA |
Browser language | French |
Result: the default configuration, GDPR FR, is loaded, even though GDPR should have applied.
Why:
Axeptio only sees the US IP provided by the VPN and associates it with CCPA regulation.
The project contains no CCPA configuration: no configuration is a candidate.
The visitor is actually a European resident to whom GDPR should apply, but Axeptio has no way of knowing this: only the IP counts.
Scenario 6 — a configuration directly targets the visitor's country
In addition to the 5 GDPR configurations above, the project contains a CCPA configuration that directly targets the country "United States", independently of its regulation. This is the most common case in practice: for example, a site with a default GDPR banner for the rest of the world, and a dedicated banner explicitly targeting a specific country (United States, Canada…).
Variable | Value |
Visitor's actual location | United States |
Detected IP | United States |
Direct country targeting | One configuration targets "United States" |
Browser language | English |
Result: the configuration directly targeting the United States is loaded.
Why:
One configuration directly targets the visitor's country (level 2 of the priority order): it becomes a candidate before regulation is even evaluated.
No other configuration directly targets the United States: it is the only candidate at this level, it is selected immediately, without even looking at the regulation or the 5 GDPR configurations.
Direct subdivision targeting (level 1, e.g., Quebec or California) works exactly the same way, with even higher priority: a configuration targeting a subdivision takes precedence over a configuration targeting the entire country.
Enable geolocation
Geolocation is configured from the configuration list of the relevant product, for Brands (Cookie banners) or Publishers (TCF cookie banner).
Go to My banners in the relevant product.
Enter a configuration.
Click the Geolocalized display button in the top right of the page.
In the Geolocation modal, activate the Enable location-based display toggle.
Select a default banner in the Default banner settings section — this configuration will be used if no other matches the visitor's location.
If you want to restrict banner display to certain countries only, activate the Banner visibility toggle and select the relevant countries. This restriction is checked before geolocation selection: a visitor located in a non-selected country will see no banner, even if a configuration would otherwise match.
Click Save and Publish for the changes to take effect.