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_viewfor 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 Wagtaildjango.template.context_processors.requestin your template settings. Wagtail's project template has it. Without it, the tag loads nothing.
Installation
-
Install the package:
pip install wagtail-google-tag
-
Add it to
INSTALLED_APPS, withwagtail.contrib.settings:INSTALLED_APPS = [ # ... "wagtail.contrib.settings", "wagtail_google_tag", # ... ]
-
Create its tables:
python manage.py migrate
-
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 %} ...
-
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.
Consent
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.
-
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.
-
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. -
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. -
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_typeoncontact_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. -
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.
-
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
collectstatichasn't run. Runpython manage.py checktoo: 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.
Links
License
BSD-3-Clause. See LICENSE.
Metadata
Release files for wagtail-google-tag 0.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wagtail_google_tag-0.2.3.tar.gz | 13.8 kB | With provenance | Details for wagtail_google_tag-0.2.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wagtail_google_tag-0.2.3-py3-none-any.whl | Python 3 | none | any | Details for wagtail_google_tag-0.2.3-py3-none-any.whl |
Total release size: 31.6 kB
Release files / wagtail_google_tag-0.2.3.tar.gz
| Download URL | wagtail_google_tag-0.2.3.tar.gz |
|---|---|
| Size | 13.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
70530b6747314a5fdd7406ec4f822f665e1b2c7c70fe51846309a139ca44e442
|
|
BLAKE2b-256 checksum How to use checksums |
55c9ced9ca7a4a20cbae060c9782307c2ec1d2383e1ea274173ef008e9ef1917
|
| 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 logRelease files / wagtail_google_tag-0.2.3-py3-none-any.whl
| Download URL | wagtail_google_tag-0.2.3-py3-none-any.whl |
|---|---|
| Size | 17.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ded749cc2ec4b59ca49b69ebbb2eaa57878a8cdceb35c626ac8a2e8c1132cb28
|
|
BLAKE2b-256 checksum How to use checksums |
ad079c8b82466ec62b14ab09dfe3274f5374f44d6683f96bdcb31846d55275ec
|
| 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 logSecurity for wagtail-google-tag 0.2.3
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.
Attestation for wagtail_google_tag-0.2.3.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 logA 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.