Klaro Geo

This plugin integrates the Klaro consent management tool with the Geolocation IP Detection Wordpress plugin to allow you to target different consent banners using Klaro.

It is designed to work with Google Tag Manager where Klaro controls the loading of Google Tag Manager. For optimal reliability, we recommend loading Google Tag Manager via the plugin settings page rather than manually adding it to your site. This ensures the GTM snippet is properly customized to integrate with Klaro.

It allows you to create and manage multiple consent banner templates, assign each template to users by location, and track consent decisions for compliance purposes.

This plugin gives you a lot of control over how consent is managed and tracked across your website. Using this plugin does not guarantee that you will be compliant with applicable laws and regulations.

You are responsible for ensuring compliance with all applicable laws and regulations.

Features

• Geolocation-Based Consent Management: Display different consent banners based on user location (country and region).
• Template System: Create and manage multiple consent banner templates.
• Google Tag Manager Integration: Built-in support for Google Tag Manager with zero-config consent mode.
• Google Consent Mode v2: Support for Google's basic and advanced consent mode.
• Simplified GTM Consent Triggers: Custom Consent Mode consent keys allow for a cleaner triggering of consented services in Google Tag Manager.
• Fallback Templates: Use strict fallback templates to prevent accidental violations of local law.
• Granular Consent Receipts: Automatically generates consent receipts stored in browser local storage for user reference if enabled. Optionally configure specific templates to archive these receipts in your WordPress database, allowing you to retain records only for jurisdictions that require it while blocking storage for others.
• Consent Buttons: Add a floating button or integrate with WordPress menus to allow users to easily access consent settings.
• Global Privacy Control (GPC): Detects the navigator.globalPrivacyControl browser signal and automatically adjusts consent defaults for affected services. Configurable per-template and per-service.
• Bidirectional Data Layer Integration: A full-duplex integration that listens for dataLayer events to trigger plugin actions, forwards native Klaro events to the dataLayer, and dispatches its own enhanced consent status events.
• Admin Debug Tools: Test different geolocation scenarios directly from the admin bar.

Requirements

• Tested on WordPress 6.3 and 6.4 (earlier versions may work but are untested)
• GeoIP Detection plugin (for geolocation features to work)

Versions

Two builds are available:

• WordPress.org (klaro-geo-{version}.zip) — Available from the WordPress plugin directory. Service callback fields (onInit, onAccept, onDecline) are removed for security. This is the recommended version for most users.
• Full (klaro-geo-{version}-full.zip) — Available from GitHub releases. Includes service callback fields that allow custom JavaScript to run on consent events. Use this version if you need direct control over service lifecycle hooks.

Both versions are functionally identical in all other respects.

Installation

1. Install the GeoIP Detection plugin from the WordPress plugins directory
2. Upload the klaro-geo folder to the /wp-content/plugins/ directory
3. Activate the plugin through the 'Plugins' menu in WordPress admin
4. Configure Klaro Geo settings under the 'Klaro Geo' menu in the WordPress admin

Configuration

Quick Start Guide

Important: Configuration order matters. You must define foundational settings (like Purposes) before you can assign them to Services or configure Translations.

Please follow the steps below in order to ensure a smooth setup and avoid having to backtrack.

1. Go to the main settings page Klaro Geo > Klaro Geo and ensure the following settings are configured correctly:

• Google Tag Manager ID is set.
• Purposes are configured as desired.

2. Go to the services page Klaro Geo > Services and configure your services

• If you plan on using consent mode, be sure that your consent mode services are configured before proceeding to the next step.
• The service-level Required and Default fields override the template-level fields of the same name. Any services that should behave differently from the templates need to be configured here. This includes services assigned to required or security purposes.
• Assign each service to one or more purposes

3. Go to the templates page Klaro Geo > Templates and customize the default template and create any other desired templates

• Ensure that your templates have the Default State setting set the desired opt-in or opt-out behavior.

4. Go to the countries page Klaro Geo > Country Settings and map a template to the Fallback Template and to your desired countries or regions.
5. Go to Google Tag Manager and configure your tags to use consent-based firing:

• For Google tags (GA4, Google Ads): fire on normal triggers (e.g., All Pages). Consent mode is handled automatically via gtag().
• For non-Google tags: use GTM's "Require additional consent for tag to fire" with custom consent keys (e.g., facebook_consent). Fire on Klaro Consent Update event.
• Alternative: Create a Data Layer Variable for acceptedServices and use Trigger Groups for more control (see Tag Trigger Setup).

General Settings

Navigate to Klaro Geo > Klaro Geo to configure the general plugin settings:

• Klaro Geo Settings:

  • Enabled Consent Receipts: Toggle to save receipt number and Klaro Config to browser local storage and the WordPress database
  • Klaro JS Version: Set the Klaro script version (changing this may not work as expected, this plugin has been tested with 0.7)
  • Klaro Script Variant: Choose between standard Klaro script or the no-CSS variant

• Google Tag Manager:

  • Google Tag Manager ID: Enter your Google Tag Manager container ID (e.g., GTM-XXXXXX)
  • Consent Mode Type: Choose between Basic and Advanced consent mode (see Basic vs Advanced Consent Mode below)

• Consent Management Buttons:

  • Enable Floating Consent Button: Create a persistent floating button that opens the Klaro service management modal
  • Button Text: Enter the text for the floating consent button
  • Button Theme: Select a style for the button
  • Button Position: Select where the button should appear on the screen
  • WordPress Menu Integration: Instructions on how to add a link that opens the Klaro service management modal into your WordPress menus
  • Shortcode: Instructions on how to use a shortcode to add a link that opens the Klaro service management modal into your WordPress pages

• Purposes:

  • Purposes (comma-separated): List of purposes by which you want to group your tags

• Data Layer Settings:

  • Suppress Individual Klaro Consent Event dataLayer Pushes: Klaro sends a "consents" event every time an individual consent toggle is changed in the consent banner. These don't take effect until the user saves their choices, at which point the plugin sends a consolidated event. Klaro Geo is configured to forward Klaro events to the dataLayer. Enabling this setting (recommended) suppresses the individual toggle events, which can pollute the dataLayer when users toggle multiple settings. Disable this only if you need to track individual consent toggle interactions within the banner.

• Debug Settings:

  • Enable Plugin Debug Logging: When enabled, the plugin will output debug messages to WordPress logs (PHP) and browser console (JavaScript). Useful for troubleshooting but should be disabled in production to reduce log noise. Note: WP_DEBUG must also be enabled for PHP logging to work.
  • Debug Countries/Regions (comma-separated): Enter a list of two-digit country codes or ISO 3166-2 region codes (e.g., US, UK, US-CA, CA-QC). These codes will populate a dropdown in the WordPress Admin Bar, allowing you to simulate browsing from those locations to test your Klaro configuration.
  • Plugin Cleanup: Remove all settings when deactivating the plugin. You will need to reconfigure everything if you reactivate the plugin.

Templates

Templates define the language, layout, and behavior of the consent banner displayed to users. Templates get assigned to countries and regions so that you can change consent features and language by jurisdiction.

Most of the template settings are derived directly from Klaro settings. Template-specific Klaro Geo settings include additional Google settings (ads_data_redaction, url_passthrough) and Consent Logging.

You can not delete templates that are currently assigned to countries or regions. To remove a template, you must first unassign it on the Country Settings page.

Navigate to Klaro Geo > Templates to manage consent banner templates.

• Basic Settings:
  • Version: Klaro configuration version.
  • Element ID: Klaro HTML element ID for the Klaro container.
• Styling:
  • Theme Color: Choose between Klaro's default light and dark themes.
  • Position: Position of the consent notice.
  • Width: Width of the consent notice.
• Behavior Settings:
  • Default State: Default state for services if the user doesn't make a choice
  • Required: When enabled, users cannot decline services. Only use for essential services that are required for your website to function. This setting can also be overridden per-service.
  • HTML Texts: Allow HTML in text fields.
  • Embedded Mode: If enabled, Klaro will render without the modal background, allowing you to embed it into a specific element of your website, such as your privacy notice.
  • No Auto Load: If enabled, Klaro will not automatically load itself when the page is being loaded. You'll need to manually trigger it.
  • Auto Focus: Automatically focus the consent modal when it appears.
  • Group by Purpose: Group services by their purpose in the consent modal.
• Cookie Settings:
  • Storage Method: Save consent choices in a cookie or local storage.
  • Cookie Name: Name of the cookie.
  • Cookie Expires (days): Set the cookie expiry duration in days.
  • Cookie Domain: Domain for the cookie.
  • Cookie Path: Path for the cookie.
• Consent Modal Settings:
  • Must Consent: If enabled, users must make a choice before using the site.
  • Accept All: Show an "Accept All" button.
  • Hide Declining All: Hide the "Decline All" button.
  • Hide Learn More: Hide the "Learn More" link.
  • Show Notice Title: Show the title in the consent notice.
  • Show Description for Empty Store: Show description text even when no services are defined.
  • Disable Powered By: Hide the "Powered by Klaro" text.
  • Additional CSS Class: Additional CSS class to add to the consent modal.
  • Default Language: Default language code (e.g., 'en', 'de'). Leave empty to use the fallback language and translation settings ('zz').

    Consent Mode Settings:

    Consent mode is always enabled. The standard Google Consent Mode signals (ad_storage, analytics_storage, ad_user_data, ad_personalization) are controlled by dedicated consent mode services configured in the Services section. Consent defaults for each service are determined by the service's required/default state and this template's Default State setting.

  • Additional Google Settings

    • ads_data_redaction: Manage the redaction of ad click identifiers when ad_storage is denied
    • url_passthrough: Manage the appending of ad click identifiers as URL parameters when ad_storage or analytics_storage is denied

  • Service Consent Defaults

    • Read-only view of the custom consent key and default state for each service
• Plugin Settings:
  • Enable Consent Logging: Log consent choices for this template in the WordPress database.

Translations:

Klaro consent translation settings. All translation settings except for service names and descriptions are managed here in the template settings.

This allows you to create language specific to a legal jurisdiction, for example "do not sell my data" notices in California, and assign the template to that location.

• Translation Settings: Configure translations for various text elements in the consent notice.
• Advanced Translations (JSON): Edit translations JSON directly. This is useful for copying and pasting translations between templates.

Country Settings

Set your fallback template, assign templates to countries and override country templates with region templates.

Navigate to Klaro Geo > Countries to assign templates to specific locations:

1. Assign a template to the Fallback Template row.
2. From the dropdown menu in the template column of your chosen country's row, select a template.
3. Select Manage Regions to override country settings in specified regions as desired.
4. Select Hide to remove a country from the Klaro Geo Country Settings table as desired.
5. Select Show/Hide Countries to add and remove countries from the Klaro Geo Country Settings table as desired.
6. Select Save Changes to apply your changes.

Services

Manage services that should show in the consent modal.

Klaro automatically manages third-party inline scripts when the following conditions are met:

• The script has a type attribute set to text/plain
• The script has a data-type attribute set to application/javascript.
• The script has a data-name attribute matching the service name as defined on this page.

Klaro Geo automatically embeds Google Tag Manager this way.

It should be possible to use this plugin to manage other inline scripts without using Google Tag Manager or to implement other tag managers. However, it will require advanced knowledge of Klaro, Google Tag Manager, and Klaro Geo to get it to work correctly.

Klaro Geo adds a Klaro Consent Update dataLayer push whenever consent is updated with custom consent keys as well as an acceptedServices array containing the names of services that are currently accepted.

Use custom consent keys with GTM's "Require additional consent for tag to fire" to gate any tag on a specific service's consent (e.g., add facebook_consent to a Facebook Pixel tag). Alternatively, use the Klaro Consent Update event with a Data Layer Variable trigger condition (e.g., consentMode.facebook_consent equals granted). The acceptedServices array is for use in situations where Google Consent Mode is not applicable (like when using a tag manager other than Google Tag Manager).

Navigate to Klaro Geo > Services to manage services:

Use the Add New Service, Edit, and Delete buttons to manage services.

Each service gets the following settings that Klaro consumes and uses:

• Name: The name of the service as it will appear in the acceptedServices array in lowercase with spaces replaced with hyphens.
• Required: Display the service but do not allow visitors to turn off the service. Overrides the template-level setting of the same name.

Functional service warning: Setting a purpose to 'functional' or 'security' or some other purpose that does not require consent does not mean the service is automatically loaded. You need to set each functional service's Required field here to "Yes" in order to automatically load the service.

• Default: Load this service by default before the consent banner is interacted with. Overrides the template-level setting of the same name.
• Purpose: Select the purpose(s) associated with this service. The list of purposes is managed on the main settings page at Klaro Geo > Klaro Geo > Purposes (comma-separated). It is best to decide on your list of purposes before you start assigning them here.
• Advanced Settings: Manage additional Klaro settings for the service (these have not been tested with the plugin).
• Callback Scripts: Customize the JavaScript functions called during consent initialization, acceptance, and decline events.

Service Translations (only shown when editing a specific service)

The default Fallback translation tab sets the Klaro zz translation key for each service.

New languages need to be configured in a template on the Templates page before you can set translation settings here.

Manage the following service-specific translation fields here:

• Title: This is the human-readable name of the service. It should be populated automatically in title-case from the service name.
• Description: A brief description of what the service does.

Consent Receipts

The Consent Receipts page lets you browse the consent receipts logged in Wordpress.

Consent receipts need to be enabled under Klaro Geo > Enable Consent Receipts for you to view data here.

You will only see data from countries / regions with a template that enables consent logging under Templates > select desired template > Enable Consent Logging.

Adding Consent Buttons

There are multiple ways to add consent management buttons to your site:

WordPress Menu Integration

You can add a consent management button to any WordPress menu using a custom link:

1. Go to Appearance > Menus in your WordPress admin
2. Create a new menu or edit an existing one
3. In the "Custom Links" section, add a link with:
   • URL: # (just a hash symbol)
   • Link Text: "Manage Cookies" or whatever text you prefer
4. Click "Add to Menu"
5. Expand the newly added menu item
6. In the "CSS Classes (optional)" field, add the class open-klaro-modal
   • IMPORTANT: While the field is labeled "optional" in WordPress, the open-klaro-modal class is required for the menu item to open the Klaro modal. Without this class, the link will not function.
7. Save the menu

When clicked, this menu item will open the Klaro consent management popup, allowing users to update their consent preferences at any time.

Shortcode

You can use the [klaro_consent_button] shortcode to add a consent button anywhere shortcodes are supported:

[klaro_consent_button text="Manage Cookie Settings" class="my-custom-class" style="button"]

Parameters:

• text: (Optional) The button text. Defaults to the text configured in settings.
• class: (Optional) Additional CSS classes to add to the button.
• style: (Optional) Set to "link" for a text link instead of a button.

Examples:

[klaro_consent_button]
[klaro_consent_button text="Privacy Settings" style="link"]
[klaro_consent_button class="button button-primary" text="Cookie Settings"]

Floating Button

The plugin also provides a floating button option that can be enabled in the settings. This button can be configured to appear at the bottom or top to the left or right of the viewport and is always accessible to visitors.

Customizing Klaro Appearance

Klaro has built-in theme settings and Klaro Geo has theme settings for the floating consent button.

Klaro Geo allows you to select either the standard Klaro script (klaro.js) or a version that does not load its own CSS (klaro-no-css.js). Both scripts provide similar functionality, but they differ in their approach to styling.

The translation settings for the plugin are managed in template and service configurations.

Developers can set custom CSS classes and override Klaro's default styles.

The GeoIP Detection plugin also includes an option to add the detected country and region as a class to the body element. This can be used to customize the appearance of the consent banner based on the visitor's location beyond the text and behavior settings provided natively by Klaro and Klaro Geo.

Klaro Script Variants

The plugin supports different Klaro script variants:

1. Standard (klaro.js): The default Klaro script with built-in styles.
2. No CSS (klaro-no-css.js): A version of Klaro without styles, which is useful if you want to use your own CSS or customize the default styles.

Google Tag Manager Integration

The plugin directly loads Google Tag Manager in a Klaro-compatible way, ensuring proper consent management.

Consent Mode (Zero-Config)

Klaro Geo automatically sets up Google Consent Mode v2 without any GTM template or additional configuration:

• Consent defaults are set via gtag('consent', 'default', ...) in the <head> before any tags load
• Consent updates are called via gtag('consent', 'update', ...) directly when users interact with the consent banner
• Custom consent types (e.g., facebook_consent) work natively with GTM's "Require additional consent for tag to fire"

This means consent mode works out of the box for both Google and non-Google tags.

GTM Consent Gate Variable (Optional)

Klaro Geo includes an optional Consent Gate Variable template for GTM. This variable acts as a consent-aware wrapper -- it passes through a value when consent is granted and returns a redacted value when denied. Useful for redacting user-provided data (email, phone) when ad_user_data is denied, or zeroing out transaction values when ad_storage is denied.

For setup instructions, see the GTM Template README.

How to Set Up GTM

1. Go to Klaro Geo > Klaro Geo > Google Tag Manager
2. Enter your Google Tag Manager ID (e.g., GTM-XXXXXX)
3. Select your Consent Mode Type (Basic or Advanced) - see Basic vs Advanced Consent Mode below
4. Save your settings

The plugin will automatically:

• Add the GTM script to your site's header (with Klaro gating in Basic mode, or ungated in Advanced mode)
• Add the GTM noscript iframe to your site's body
• Configure consent callbacks to manage GTM's consent mode

Basic vs Advanced Consent Mode

Klaro Geo supports two consent mode types that control how Google Tag Manager interacts with the consent banner. Both modes use Google Consent Mode v2 and the Klaro Geo GTM community template.

Basic Consent Mode (Default)

In Basic mode, GTM is completely blocked until the user consents to the google-tag-manager service. No data is sent to Google before consent.

How it works:

1. The GTM script tag is rendered with type="text/plain" and data-name="google-tag-manager", which prevents execution
2. When the user grants consent to the google-tag-manager service, Klaro changes the type to text/javascript, which triggers GTM to load
3. The GTM community template sets consent defaults and then updates consent state based on the user's choices
4. Tags fire according to their consent requirements

When to use Basic mode:

• When you want zero data collection before explicit consent
• For the strictest interpretation of GDPR and similar regulations
• When you don't need Google's behavioral modeling features

WordPress settings:

• Go to Klaro Geo > Klaro Geo > Google Tag Manager
• Set Consent Mode Type to Basic

Advanced Consent Mode

In Advanced mode, GTM loads immediately (without Klaro gating) but all consent signals default to denied. Google tags like GA4 can send cookieless pings before consent, enabling behavioral modeling and basic measurement without cookies.

How it works:

1. The GTM script tag is rendered as a normal `