Skip to main content

Wagtail Google tag

Google tag configuration UI (GA4) for Wagtail. Our ultimate goal is everything you need to do to set up GA, you do through the Wagtail admin.

Claude Code was used with oversight by the maintainer.

Summary of Purpose

“Wagtail Google tag” adds Google tags for Google Analytics 4 to a Wagtail site, exposing as much setup and configuration as possible via the admin UI and providing a clear checklist of what has to be done outside that. The focus is on sending data to GA.

It doesn't bring Google Analytics into the Wagtail admin: reports stay in Google Analytics, and so do its own settings, such as data retention and key events. It also doesn't load a Tag Manager container of your own.

Progress so far

  • A page_view for every page, sent by Google's tag
  • Google Analytics' enhanced measurement (scrolls, outbound clicks and site search), per your setup in Google Analytics
  • Tag is kept out of preview views automatically (non-configurable)
  • Settings available under Settings → Google tag, per the table below
  • In your templates, add an HTML attribute to a link or button to enable click events.

Settings reference

Each site has its own settings, under Settings → Google tag.

Setting Default What it does
Measurement ID Blank The site's GA4 measurement ID (G-…). Blank means no tag.
Deny analytics by default in Europe On When on, visitors in Europe start with analytics and advertising signals denied, as in Consent. When off, they start like everyone else.
Site uses Google Ads Off When on, advertising signals are granted by default outside Europe, and a banner's marketing choice sets them. When off, they're denied for every visitor.
Leave out of tracking Nothing checked Roles that will not get a tag, as a list of checkboxes. See Who is tracked.
Track email and phone links On When on, a click on an email or phone link sends contact_link_click with link_type set to email or phone.

Who is tracked

Two settings decide this, and they do different jobs:

  • Leave out of tracking decides whether a visitor gets Google's tag at all. A visitor with a checked role gets no tag, and nothing about their visit is sent. Use this to leave logged-in Editors untracked, for example.
  • Consent decides what the tag may do for everyone else. A visitor who hasn't agreed to analytics, or has withdrawn, still gets the tag, but it sets no analytics cookies and sends Google only cookieless pings. See Consent.

Neither overrides the other. Everyone gets the tag unless you check a role under Leave out of tracking:

Checkbox Who it leaves out
Anyone signed in Every signed-in user. It overrides the rest of the list.
Administrators Users with Wagtail's Administrator status
Signed in, with no group Signed-in users who belong to no group
Each group, by name Members of that group, such as Editors or Moderators

A user with several roles is left out if any one of them is checked. Visitors who aren't signed in are always tracked. Groups are the ones under Settings → Groups, and a group you add there appears in the list.

Requirements

  • Wagtail 7.4, 8.0 or 8.1, with the Python and Django versions each of them supports
  • wagtail.contrib.settings, which comes with Wagtail
  • django.template.context_processors.request in your template settings. Wagtail's project template has it. Without it, the tag loads nothing.

Installation

  1. Install the package:

    pip install wagtail-google-tag
    
  2. Add it to INSTALLED_APPS, with wagtail.contrib.settings:

    INSTALLED_APPS = [
        # ...
        "wagtail.contrib.settings",
        "wagtail_google_tag",
        # ...
    ]
    
  3. Create its tables:

    python manage.py migrate
    
  4. Add the tag near the top of <head> in your base template:

    {% load wagtail_google_tag %}
    <!doctype html>
    <html>
      <head>
        <meta charset="utf-8">
        {% google_tag %}
        ...
    
  5. In the Wagtail admin, go to Settings → Google tag and enter your GA4 measurement ID. In Google Analytics, it's under Admin → Data streams, in your web stream.

The tag's script is one of the package's static files. On a deployed site, run collectstatic after you install or upgrade the package, as for any app's static files.

Usage

Click events

Add data-google-tag-event to any link or button to send that event when it's clicked. Add parameters as JSON in data-google-tag-params:

<a href="/pricing/"
   data-google-tag-event="select_content"
   data-google-tag-params='{"content_type": "cta", "content_id": "pricing-hero"}'>
  See pricing
</a>

A click sends one event. An email or phone link with its own data-google-tag-event sends only that event, not contact_link_click as well.

From scripts

The tag defines window.wagtailGoogleTag. It's there on every page, and sends nothing when the tag isn't loaded, so scripts never need to check:

window.wagtailGoogleTag.track("generate_lead", { method: "newsletter" });

Templates outside your base template

A template that doesn't extend your base template, such as a 404 page, needs the tag too:

{% load wagtail_google_tag %}
...
{% google_tag %}

Page views

Google's tag sends the page view itself, with the page's address and title.

Google has deprecated the config command, and the tags of newer Google Analytics properties ignore it. So the package sends data only on events.

Testing your setup

Visit your site, click around, and watch Google Analytics' Realtime report (Reports → Realtime). Google gives Realtime's delay as typically a few minutes, with no guarantee. Select an event there to see the parameters sent with it. If your own role is checked under Leave out of tracking, visit while signed out of Wagtail.

Content Security Policy

If your site has a Content Security Policy, allow Google's tag in it. Google lists the sources Google Analytics needs in its Content Security Policy guide: https://www.googletagmanager.com for scripts, and more for images and connections. The package itself uses no inline scripts.

Before a visitor has made a choice, Google's tag starts with these Consent Mode defaults:

Visitors Analytics Advertising signals
In the European Economic Area, the UK and Switzerland Denied Denied
Everywhere else Granted Denied, unless "Site uses Google Ads" is on

Google works out where a visitor is. Denied analytics means no analytics cookies: Google Analytics receives only cookieless pings, which Google says can't directly identify an individual, and uses them to model the data that's missing. To start with analytics granted everywhere, turn off Deny analytics by default in Europe.

This is what Google calls advanced consent mode: the tag loads for every visitor and adjusts to their consent, rather than staying off until they agree. It keeps the most measurement Consent Mode allows. A cookieless ping still reaches Google, so check that this fits the rules that apply to your site.

A consent banner updates these defaults with the visitor's choice, in either of two ways:

// Call the function
window.wagtailGoogleTag.consent({ analytics: true, marketing: false });

// Or send this event on document
document.dispatchEvent(
  new CustomEvent("wagtail-cookie-consent:change", {
    detail: { analytics: true, marketing: false },
  }),
);

analytics sets analytics storage. marketing sets the advertising signals, and only when Site uses Google Ads is on. A banner that runs on each page load once a visitor has chosen should send the choice each time, as early as it can: Google's tag waits half a second for that update before it sends anything, and a choice that arrives later misses the page view.

When a visitor refuses or withdraws analytics, the package also deletes Google Analytics' cookies (_ga and those starting with _ga_), which Google's tag would otherwise leave in place.

Google Analytics has two settings of its own that touch these defaults. They're in the property's Google tag settings, under Admin → Data streams → your stream → Configure tag settings:

  • Override consent mode defaults: leave it unset. If it's set, it replaces the defaults above.
  • Manage default consent settings: choose "No. Do not automatically mark this data as consented."

The event comes from wagtail-cookie-consent, a companion package, but any banner can send it or call the function. With that package, put {% google_tag %} before {% cookie_consent %}.

Google Analytics setup checklist

These are set in Google Analytics, not in Wagtail. All of them are under Admin in your property.

  1. Data retention. Under Data collection and modification → Data retention, choose how long Google Analytics keeps event data: 2 months, which is the default, or 14 months. Match what your privacy notice says.

  2. Enhanced measurement. Under Data collection and modification → Data streams → your stream, check that Enhanced measurement is on. It's what sends scrolls, outbound clicks and site search. The search page in Wagtail's project template works as it is: its ?query= is one of the parameters Google looks for.

  3. Key events. Under Data display → Events, mark the events that count as results for you, such as generate_lead. An event appears there once Google Analytics has received it. To set one up before that, create the event there under its exact name, with Create with code and no default value.

  4. Custom dimensions. A parameter on one of your events shows in reports only after you create a custom dimension for it. Under Data display → Custom definitions, create one with the scope Event for each parameter you want to report on. For the package's own event, that's link_type on contact_link_click. Type the parameter's name if the list doesn't offer it. A dimension fills in only from the day you create it.

  5. Google tag settings. Under Data collection and modification → Data streams → your stream → Configure tag settings:

    • Allow user-provided data capabilities: when it's on, Google's tag may look for email addresses on your pages. Turn it off if no email address should reach Google Analytics.
    • Override consent mode defaults: leave it unset, as in Consent.
    • Manage default consent settings: choose "No. Do not automatically mark this data as consented."

    Some of these are behind Show more. If Google asks you to publish a new version, do: the settings don't apply until then.

  6. Check that it works, as in Testing your setup.

Troubleshooting

  • No tag on the page: the measurement ID is blank, your role is left out, the page is a preview, or collectstatic hasn't run. Run python manage.py check too: it warns when the request isn't in the template context.
  • Nothing in Realtime: wait a few minutes, and turn off any ad blocker or tracking protection in your browser.
  • A parameter isn't in reports: create a custom dimension for it (checklist item 4).
  • A Google tag setting has no effect: publish the new version (checklist item 5).
  • Little data from Europe: expected while analytics is denied by default. See Consent.

Privacy notes

The package sends no personal data. Email and phone link events carry only link_type, never the address or number. Google's own rules forbid personal data in Google Analytics, so keep it out of your own event parameters too.

License

BSD-3-Clause. See LICENSE.

Metadata

Release files for wagtail-google-tag 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wagtail-google-tag 0.2.2
File Size Uploaded Provenance Actions
wagtail_google_tag-0.2.2.tar.gz 13.7 kB With provenance Details for wagtail_google_tag-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wagtail-google-tag 0.2.2
File Interpreter ABI Platform Actions
wagtail_google_tag-0.2.2-py3-none-any.whl Python 3 none any Details for wagtail_google_tag-0.2.2-py3-none-any.whl

Total release size: 31.4 kB

Release files / wagtail_google_tag-0.2.2.tar.gz

Download URL wagtail_google_tag-0.2.2.tar.gz
Size 13.7 kB
Tags Source
SHA-256 checksum
How to use checksums
5ab0e11fd2c336631ece8a2160629e5a30524c5c8684520d9df5b766e1bb4ce7
BLAKE2b-256 checksum
How to use checksums
7d1d37593aa172655efd2e09d11d6a1df70de4424807749479334ac9a80f9b24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / wagtail_google_tag-0.2.2-py3-none-any.whl

Download URL wagtail_google_tag-0.2.2-py3-none-any.whl
Size 17.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ca3c2fae5aa02cd4510a9f506f89fd79432989b2f9854c7d28d039b68af828e3
BLAKE2b-256 checksum
How to use checksums
556848f3eea23f122a84465df92b7290520dc947f0a2a34ca5d2e341c859572f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for wagtail-google-tag 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for wagtail_google_tag-0.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page