Google Analytics Integration Plugin

Google Analytics provides reports for website traffic, acquisition, engagement, events, and other measurements. The Google Analytics Integration plugin connects a Publii site through the current Google tag or Google Tag Manager without requiring changes to the theme.

The plugin supports direct Google tag configuration, a GTM web container, complete blocking through Publii's Cookie Banner, and Google Consent Mode v2. It also adds the Google-issued Developer ID assigned to the Publii CMS integration automatically. Site owners enter only their own Google tag or GTM container ID.

Requirements

Publii 0.45 or newer.
A Google account.
A Google Analytics 4 property with a web data stream for a direct Analytics setup, or a published Google Tag Manager web container.
A current Google tag ID beginning with G-, GT-, AW-, or DC-, or a GTM container ID beginning with GTM-.
An existing Publii Cookie Group if you use complete pre-consent blocking.
A configured Publii Cookie Banner and Google Consent Mode v2 mapping if you use Advanced mode.

Google Analytics and Google Tag Manager are services operated by Google and are separate from the Publii plugin. Review Google's terms, your privacy notice, the data you collect, and the consent requirements that apply to your website before publishing the integration.

Installing the plugin

Open Publii's App Menu using the three-dot icon in the top-right corner.
Select Plugins.
Click Get More Plugins to open the Publii Plugin Marketplace.
Open the Google Analytics plugin page and download the installation package.
Return to the Plugins screen in Publii and click Install Plugin.
Select the downloaded ZIP file. Do not extract it before installation.

Choosing an integration method

Select one of the following methods in the plugin options:

Google tag (gtag.js) – Publii loads the Google tag directly and sends its configuration to the destination connected to the entered tag ID. Use this method for a focused setup that you want to control from the plugin.
Google Tag Manager – Publii loads a GTM web container. Tags, triggers, variables, and tag-level consent requirements are configured in Google Tag Manager rather than in the plugin.

Do not deploy the same Google Analytics page-view setup through both methods unless you have deliberately configured one of them not to send a duplicate page view. Also check the theme, Custom HTML, and other plugins for an existing Google tag or GTM container.

Finding a Google Analytics Measurement ID

Use these steps for a standard Google Analytics 4 setup with the direct Google tag:

Sign in to Google Analytics and open the correct account and property.
Open Admin.
Under the property settings, select Data streams.
Open the web data stream for the Publii site.
Under Stream details, copy the Measurement ID. It normally begins with G-.
In Publii, select Google tag (gtag.js) and paste the ID into Google tag ID.

Copy only the ID, not the complete script shown under Google's installation instructions. See Google's Find your Google tag ID guide if the property interface has changed.

Using other Google tag IDs

The direct method also accepts current IDs beginning with GT-, AW-, and DC-. These IDs can connect the Google tag to destinations such as Google Ads or Floodlight. Copy the ID from the relevant Google product and confirm that its destination and event configuration match the measurement you intend to use.

Identifiers beginning with UA- belong to the retired Universal Analytics platform and are not supported. The plugin does not generate code for them.

Finding and preparing a GTM container

Sign in at Google Tag Manager.
Open the web container used by the Publii site.
In the Workspace, copy the public container ID displayed near the top. It begins with GTM-.
In Publii, select Google Tag Manager and paste that ID into Google tag ID.

Copy only the GTM container ID. The plugin generates the container installation code, so do not paste either of Google's complete script blocks into Publii.

Adding Google Analytics inside GTM

Loading a GTM container does not create a Google Analytics tag inside that container. Configure and publish the required tag in Google Tag Manager:

Open the container and select Tags → New.
Select Google Tag as the tag type.
Enter the Google tag ID connected to the correct Google Analytics property or other destination.
Select the trigger required by your setup. Google currently recommends Initialization – All Pages for a standard Google tag.
Save the tag, use GTM Preview to test it, and publish the container.

See Google's Google tag setup for Tag Manager guide for the current GTM workflow.

Activating the plugin

Open Tools & Plugins in Publii.
Find Google Analytics Integration and enable its switch.
Click the plugin card to open its options.
Select the integration method and enter the appropriate ID.
Review the page-view, Preview, and consent options, then save the changes.
Regenerate and publish the website.

The plugin generates no integration code when the entered ID is missing or invalid. It also stops generation when Basic mode is enabled without Publii's Cookie Banner or when Advanced mode lacks the required Publii Google Consent Mode configuration. In Basic mode, a valid but mismatched Cookie Group ID can leave the integration blocked after the visitor gives consent.

Google Analytics plugin options

Configuration

Integration method – Selects the direct Google tag or Google Tag Manager. Options that apply only to the direct tag are hidden when GTM is selected.
Google tag ID – The ID loaded by the selected integration. Enter a value beginning with G-, GT-, AW-, or DC- for the direct Google tag. Enter a value beginning with GTM- for Google Tag Manager. The plugin trims the value and normalizes letters to uppercase.
Send the initial page view – Lets the direct Google tag send its standard initial page_view event. It is enabled by default. Disable it only when another script or measurement setup sends the initial page view. This option does not configure page views inside GTM.
Additional gtag commands – Adds optional JavaScript commands after the direct tag's main gtag('config', ...) command. Enter commands only, without opening or closing script tags and without the complete Google tag snippet. The plugin ignores the entire field if it contains a script tag.
Output code in Preview Mode – Includes the selected integration in pages opened through Publii Preview. It is disabled by default because preview visits can enter analytics reports. Enable it temporarily when inspecting generated code or network requests.

Additional gtag commands is intended for developers. A syntax error can prevent the inline Google tag configuration from running. Test every change and do not send personally identifiable information through event parameters or custom fields.

Cookie Banner integration

Require consent before loading (Basic mode) – Connects the integration to a selected Publii Cookie Group. Publii blocks the complete Google tag or the entire GTM container until the visitor accepts that group. Before consent, Google scripts do not load and this integration sends no requests to Google.
Cookie Group ID – The internal ID of an existing group under Site Settings → Privacy Settings → Cookie Groups. It appears when Basic mode is enabled. Use letters, numbers, hyphens, or underscores, with a letter or number as the first character.
Use Publii Google Consent Mode v2 (Advanced mode) – Loads the Google tag or GTM container immediately after applying Publii's saved or default consent state. Consent-aware Google tags adapt to the configured state. When storage consent is denied, they can send measurements without cookies.

Basic and Advanced modes are alternatives. When both are disabled, the plugin loads the selected integration immediately without supplying a consent state. Use that setup only when another valid consent implementation covers the tag or when prior consent is not required for your configuration and visitors.

Configuring complete pre-consent blocking

Use Basic mode when no Google script or request from this integration should load before the visitor accepts a Cookie Group.

Open Site Settings → Privacy Settings.
Enable the Cookie Banner and its advanced cookie configuration.
Create or review the group used for analytics or other Google tag consent.
Set a Group ID, such as analytics. The visible group name can be different; the plugin requires the internal Group ID.
Open the Google Analytics plugin and enable Require consent before loading (Basic mode).
Enter the exact same value in Cookie Group ID.
Save the settings, regenerate the website, and test the banner in a new browser profile.

Before consent, the direct Google tag and its initialization code are blocked together. For GTM, the entire container and every tag inside it are blocked. The plugin also omits GTM's noscript iframe whenever a Publii consent option is active.

If the Cookie Group ID does not exactly match an available group, the blocked scripts may never be released. Check spelling and capitalization when the integration remains blocked after consent. Read the Publii Cookie Banner documentation for the current banner settings.

Configuring Advanced Google Consent Mode v2

Advanced mode does not provide complete pre-consent blocking. The plugin sets the consent state before loading the Google tag or GTM container. Consent-aware Google tags can send consent information and measurements without cookies while the relevant storage state is denied. When the visitor accepts a mapped Cookie Group, Publii updates the corresponding consent types.

Open Site Settings → Privacy Settings.
Enable the Cookie Banner and Advanced Cookies Configuration.
Create the Cookie Groups required by the website's consent choices.
Enable Google Consent Mode v2.
Review the default state. Set each consent type to the state that should apply before the visitor makes a choice. Where explicit consent is required, the relevant default should normally be denied.
Add a mapping for each Cookie Group and select the consent types that accepting that group should grant.
Assign analytics_storage to the group used for analytics consent.
If the site uses Google Ads or advertising features, assign ad_storage, ad_user_data, and ad_personalization to the appropriate group or groups.
Map functionality_storage, personalization_storage, or security_storage only when they apply to tags and choices on the website.
Open the plugin and enable Use Publii Google Consent Mode v2 (Advanced mode).
Save the settings, regenerate the website, and verify the defaults and updates with Google Tag Assistant.

Cookie Group names are not prescribed by Google or the plugin. What matters is the mapping between each visitor choice and the consent types it grants. See Publii's Google Consent Mode v2 documentation and Google's Consent mode overview.

Using consent with Google Tag Manager

In Basic mode, Publii blocks the complete GTM container. Use this only when every tag in the container can wait for the same Cookie Group. Tags for analytics, advertising, chat, embeds, or other purposes may require different consent categories.

In Advanced mode, Publii sets the default Google consent state before the GTM loader runs. Google tags have built-in consent checks and adapt to supported consent types. Third-party and Custom HTML tags do not automatically gain the same behavior; configure their triggers and additional consent checks inside GTM.

If the container already contains a consent template or Custom HTML that sets Google consent defaults, review it before enabling Publii Advanced mode. Two implementations can send conflicting default or update commands. Use Google Tag Assistant to confirm which consent command runs first and which state reaches each tag.

Updating from version 1.x

Version 2.0.0 is a major update for current Google tags and requires Publii 0.45 or newer. Update Publii before installing the new plugin version if the site uses an older release.

The plugin retains the existing integration method, ID, additional commands, Preview Mode, Cookie Banner integration, and Cookie Group ID. A version 1.x configuration with a current, valid ID can continue to generate code after the update. Advanced Consent Mode is disabled until you choose and configure it.

Migration steps

Create a backup of the Publii site before installing the major update.
Confirm that the site uses Publii 0.45 or newer.
Install Google Analytics Integration 2.0.0 and open its options.
Confirm that Integration method matches the intended Google tag or GTM setup.
Review Google tag ID. Replace every retired UA- identifier with a current Google tag ID, or enter a valid GTM- container ID when using Tag Manager.
Review Additional gtag commands. Remove complete script elements and leave only valid JavaScript commands intended to run after the main configuration.
Choose the consent approach. Keep Basic mode for complete blocking, or configure Publii Google Consent Mode v2 before enabling Advanced mode.
If Basic mode is enabled, confirm that the Cookie Banner is active and that Cookie Group ID exactly matches an existing group.
Regenerate the site and test the published output before deploying the update to production.

Removed IP anonymization option

Version 1.x included an Enable IP anonymization option designed for Universal Analytics. Google states that IP masking is not necessary in Google Analytics 4 because individual IP addresses are not logged or stored. Version 2.0.0 therefore removes the option without adding a replacement.

The removal does not make a Google Analytics setup private or remove the need to review consent and disclosure requirements. Google Analytics can still collect other measurement data according to the property's settings, enabled features, tag configuration, and visitor consent. See Google's legacy IP masking documentation for the distinction between Universal Analytics and GA4.

Stricter validation

Version 2.0.0 validates the selected ID format and required consent configuration before generating code. A value that produced incomplete output in version 1.x may now cause the integration to output nothing. The most common examples are a retired UA- ID, a Google tag ID entered while GTM is selected, a GTM ID entered while the direct tag is selected, or an invalid Cookie Group ID.

Testing the integration

Regenerate and publish the site to a staging or public HTTPS URL.
Open Google Tag Assistant, enter the published URL, and start a session.
For the direct method, confirm that the expected Google tag is detected and that the Summary contains the expected page event.
For GTM, confirm that the expected container loads, the Google tag inside it fires on the intended trigger, and the published container version is current.
Open Google Analytics Realtime and confirm that the test visit and page view appear.
Confirm that one page load does not create duplicate page views.
Repeat the test for every consent state used by the site.

In the browser's developer tools, the Network panel can also be filtered for googletagmanager.com and google-analytics.com. Ad blockers, browser privacy features, Content Security Policy rules, and consent settings can block these requests.

Testing Basic mode

Use a new browser profile or clear the site's saved consent.
Open the published site without accepting the selected Cookie Group.
Confirm that the Google tag or GTM container and related Google requests are absent.
Accept the selected group.
Confirm that the integration loads and that the expected event reaches Tag Assistant and Google Analytics.

Tag Assistant may initially report that it cannot connect when the Google tag or GTM container is completely blocked. In Basic mode, this is expected before consent.

Testing Advanced mode

Use a new browser profile or clear the site's saved consent.
Start a Tag Assistant session and select the earliest Consent event.
Confirm that the On-page Default values match the defaults configured in Publii for analytics_storage, ad_storage, ad_user_data, and ad_personalization.
Accept a Cookie Group and select the latest Consent event.
Confirm that the On-page Update grants only the consent types mapped to that group.
Reject or withdraw consent, reload when Publii requests it, and confirm that the next page starts with the expected default state.

Requests without analytics cookies can appear while consent is denied in Advanced mode. This is expected Consent Mode behavior. Use Basic mode when the requirement is to send no Google requests before consent. Google's consent verification guide explains the corresponding Tag Assistant checks.

Preview Mode

The plugin does not output the Google tag or GTM container in Publii Preview unless Output code in Preview Mode is enabled. This default prevents local preview activity from entering analytics reports.

Enable the option temporarily when you need to inspect generated code. Consent behavior and Google services can differ on a local preview address, so use a staging or public URL for the final Tag Assistant and Realtime checks.

Troubleshooting

No Google code appears in the generated page – Confirm that the plugin is enabled, Preview output is enabled when testing Preview, and the ID matches the selected integration method. IDs beginning with UA- are rejected. If a consent method is active, review the required Publii Privacy Settings.
The Google tag loads but Analytics receives no data – Confirm that the ID belongs to the correct GA4 web data stream, review consent, test without an ad blocker, and check Tag Assistant and Realtime. Make sure another command has not disabled the initial page view.
The GTM container loads but Analytics receives no data – Confirm that the container contains a Google tag with the correct destination, a suitable trigger, and a published version. Loading the container alone does not create an Analytics tag.
Reports contain duplicate page views – Check the theme, Custom HTML, other plugins, and GTM for another Google tag. If another implementation intentionally sends the initial page view, disable Send the initial page view for the direct tag.
Tracking remains blocked after accepting the Cookie Group – Confirm that the Cookie Group ID in the plugin exactly matches the internal Group ID in Privacy Settings, including capitalization, and that advanced Cookie Banner configuration is enabled.
Google requests appear before consent – In Advanced mode, requests without cookies are expected. Select Basic mode for complete pre-consent blocking. Also check the theme, GTM, and other plugins for a second Google integration.
Cookies appear while an Advanced-mode state is denied – Check Publii's default consent state and group mappings, then inspect Tag Assistant's earliest Consent event. Review every Google and third-party tag in GTM for built-in and additional consent checks.
Tag Assistant cannot connect before consent – This is expected when Basic mode completely blocks the Google tag or GTM container. Accept the selected group and reconnect.
Additional commands do not run – Remove opening and closing script tags. Check the browser console for syntax errors and confirm that the commands use the global gtag function.
Preview visits appear in Analytics – Disable Output code in Preview Mode and regenerate the preview.
Consent state is inconsistent in GTM – Check for another consent template or Custom HTML tag that sets default or update commands. Keep one coordinated source of consent state and verify command order in Tag Assistant.

For current implementation details, see Google's guides for finding a Google tag ID, setting up a Google tag in GTM, Consent Mode, and verifying the Google tag.