wagtail-google-tag 0.1.0__tar.gz

wagtail_google_tag-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: wagtail-google-tag
+Version: 0.1.0
+Summary: Google tag (GA4) for Wagtail, set up in the Wagtail admin: per-site settings, Consent Mode defaults, page data and click events.
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Framework :: Wagtail
+Classifier: Framework :: Wagtail :: 7
+Classifier: Framework :: Wagtail :: 8
+Requires-Dist: django>=5.2
+Requires-Dist: wagtail>=7.4
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Limitless-Horizons/wagtail-google-tag
+Project-URL: Repository, https://github.com/Limitless-Horizons/wagtail-google-tag
+Project-URL: Changelog, https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/README.md
+Project-URL: Issues, https://github.com/Limitless-Horizons/wagtail-google-tag/issues
+Description-Content-Type: text/markdown
+
+# Wagtail Google tag
+
+Google tag (GA4) for Wagtail. Goal is everything you need to do to set up GA, you do through the Wagtail admin: per-site settings, Consent Mode defaults, page data and click events.
+
+Claude Code was used with oversight by the maintainer.
+
+## What it is
+
+Wagtail Google tag adds Google's tag for Google Analytics 4 to a Wagtail site. Each site's measurement ID and options are set in the Wagtail admin. The tag loads with Consent Mode defaults that keep visitors in Europe out of analytics cookies until they agree, and it stays out of previews and away from signed-in editors. Pages can add their own data to each page view, and links and buttons can send events with two HTML attributes.
+
+It doesn't bring Google Analytics into the Wagtail admin: reports, key events and data retention stay in Google Analytics. It also doesn't load Google Tag Manager containers or send server-side events.
+
+## Requirements
+
+- Wagtail 7.4, 8.0 or 8.1, with the [Python and Django versions](https://docs.wagtail.org/en/stable/releases/upgrading.html#compatible-django-python-versions) each of them supports
+- `wagtail.contrib.settings`, which comes with Wagtail
+
+## Installation
+
+1. Install the package:
+
+   ```sh
+   pip install wagtail-google-tag
+   ```
+
+2. Add it to `INSTALLED_APPS`, with `wagtail.contrib.settings`:
+
+   ```python
+   INSTALLED_APPS = [
+       # ...
+       "wagtail.contrib.settings",
+       "wagtail_google_tag",
+       # ...
+   ]
+   ```
+
+3. Create its table:
+
+   ```sh
+   python manage.py migrate
+   ```
+
+4. Add the tag near the top of `<head>` in your base template:
+
+   ```django
+   {% 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**.
+
+## What you get out of the box
+
+- A `page_view` for every page, with GA's built-in `content_group` set to the page type, such as "Blog page".
+- Google Analytics' own automatic tracking (enhanced measurement), such as scrolls, outbound clicks and site search, as you set it up in Google Analytics.
+- [Consent Mode](#consent) defaults: analytics denied in Europe until a visitor agrees, and Google's advertising signals denied everywhere unless your site uses Google Ads.
+- A `contact_link_click` event when a visitor clicks an email or phone link. Google Analytics' automatic tracking doesn't cover these.
+- Nothing sent from Wagtail previews, or for signed-in users such as editors.
+
+## 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`:
+
+```html
+<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.
+
+### Page data
+
+A page model can supply the parameters for its page view with `get_google_tag_params()`. Start from the defaults to keep the content group:
+
+```python
+from wagtail.models import Page
+from wagtail_google_tag.tag import default_page_params
+
+
+class BlogPage(Page):
+    ...
+
+    def get_google_tag_params(self):
+        params = default_page_params(self)  # {"content_group": "Blog page"}
+        params["blog_category"] = self.category.name
+        return params
+```
+
+To see a parameter like `blog_category` in Google Analytics' reports, register it there as a custom dimension.
+
+### 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:
+
+```js
+window.wagtailGoogleTag.track("generate_lead", { method: "newsletter" });
+```
+
+### Templates without a Wagtail page
+
+Pages that aren't Wagtail pages, such as a 404 page, can pass their own parameters:
+
+```django
+{% google_tag content_group="Not found" %}
+```
+
+These are added to the page's own parameters, and win if both set the same one.
+
+## 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. To start with analytics granted everywhere, turn off **Deny analytics by default in Europe**.
+
+A consent banner updates these defaults with the visitor's choice, in either of two ways:
+
+```js
+// 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. In Europe, Google's tag waits half a second for that update before it sends anything.
+
+The event comes from [wagtail-cookie-consent](https://github.com/Limitless-Horizons/wagtail-cookie-consent), a companion package in development, but any banner can send it or call the function.
+
+## 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, unless the Django setting below supplies one. |
+| Deny analytics by default in Europe | On | The Europe defaults in [Consent](#consent). |
+| Site uses Google Ads | Off | When off, advertising signals are denied for every visitor. |
+| Track signed-in users | Off | When off, visits by signed-in users aren't tracked. |
+| Track email and phone links | On | Sends `contact_link_click` with `link_type` set to `email` or `phone`. |
+| Debug mode | Off | Sends events to Google Analytics' DebugView, for testing. |
+
+`WAGTAIL_GOOGLE_TAG_MEASUREMENT_ID` in your Django settings is a fallback, used by any site whose measurement ID is blank. It's useful for moving an existing tag over, or for setting the ID from an environment variable.
+
+### Testing your setup
+
+Turn on **Debug mode**, then visit your site in a private window, since your own signed-in visits aren't tracked. Your page views and events show up in Google Analytics under **Admin → DebugView**. Turn debug mode off when you're done.
+
+### Content Security Policy
+
+If your site has a Content Security Policy, allow Google's tag: `https://www.googletagmanager.com` in `script-src`, and Google Analytics' collection domains, such as `https://*.google-analytics.com`, in `connect-src`. The package itself uses no inline scripts.
+
+## 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.
+
+Some things are set in Google Analytics, not here:
+
+- How long data is kept (Google's default is two months)
+- Which events count as key events, such as `generate_lead`
+- Custom dimensions for your own parameters
+- Enhanced measurement: scrolls, outbound clicks, site search and the rest
+
+## Links
+
+- [Changelog](https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/CHANGELOG.md)
+- [Contributing](https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/CONTRIBUTING.md)
+- [Security policy](https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/SECURITY.md)
+
+## License
+
+BSD-3-Clause. See [LICENSE](https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/LICENSE).

wagtail_google_tag-0.1.0/README.md

@@ -0,0 +1,190 @@
+# Wagtail Google tag
+
+Google tag (GA4) for Wagtail. Goal is everything you need to do to set up GA, you do through the Wagtail admin: per-site settings, Consent Mode defaults, page data and click events.
+
+Claude Code was used with oversight by the maintainer.
+
+## What it is
+
+Wagtail Google tag adds Google's tag for Google Analytics 4 to a Wagtail site. Each site's measurement ID and options are set in the Wagtail admin. The tag loads with Consent Mode defaults that keep visitors in Europe out of analytics cookies until they agree, and it stays out of previews and away from signed-in editors. Pages can add their own data to each page view, and links and buttons can send events with two HTML attributes.
+
+It doesn't bring Google Analytics into the Wagtail admin: reports, key events and data retention stay in Google Analytics. It also doesn't load Google Tag Manager containers or send server-side events.
+
+## Requirements
+
+- Wagtail 7.4, 8.0 or 8.1, with the [Python and Django versions](https://docs.wagtail.org/en/stable/releases/upgrading.html#compatible-django-python-versions) each of them supports
+- `wagtail.contrib.settings`, which comes with Wagtail
+
+## Installation
+
+1. Install the package:
+
+   ```sh
+   pip install wagtail-google-tag
+   ```
+
+2. Add it to `INSTALLED_APPS`, with `wagtail.contrib.settings`:
+
+   ```python
+   INSTALLED_APPS = [
+       # ...
+       "wagtail.contrib.settings",
+       "wagtail_google_tag",
+       # ...
+   ]
+   ```
+
+3. Create its table:
+
+   ```sh
+   python manage.py migrate
+   ```
+
+4. Add the tag near the top of `<head>` in your base template:
+
+   ```django
+   {% 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**.
+
+## What you get out of the box
+
+- A `page_view` for every page, with GA's built-in `content_group` set to the page type, such as "Blog page".
+- Google Analytics' own automatic tracking (enhanced measurement), such as scrolls, outbound clicks and site search, as you set it up in Google Analytics.
+- [Consent Mode](#consent) defaults: analytics denied in Europe until a visitor agrees, and Google's advertising signals denied everywhere unless your site uses Google Ads.
+- A `contact_link_click` event when a visitor clicks an email or phone link. Google Analytics' automatic tracking doesn't cover these.
+- Nothing sent from Wagtail previews, or for signed-in users such as editors.
+
+## 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`:
+
+```html
+<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.
+
+### Page data
+
+A page model can supply the parameters for its page view with `get_google_tag_params()`. Start from the defaults to keep the content group:
+
+```python
+from wagtail.models import Page
+from wagtail_google_tag.tag import default_page_params
+
+
+class BlogPage(Page):
+    ...
+
+    def get_google_tag_params(self):
+        params = default_page_params(self)  # {"content_group": "Blog page"}
+        params["blog_category"] = self.category.name
+        return params
+```
+
+To see a parameter like `blog_category` in Google Analytics' reports, register it there as a custom dimension.
+
+### 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:
+
+```js
+window.wagtailGoogleTag.track("generate_lead", { method: "newsletter" });
+```
+
+### Templates without a Wagtail page
+
+Pages that aren't Wagtail pages, such as a 404 page, can pass their own parameters:
+
+```django
+{% google_tag content_group="Not found" %}
+```
+
+These are added to the page's own parameters, and win if both set the same one.
+
+## 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. To start with analytics granted everywhere, turn off **Deny analytics by default in Europe**.
+
+A consent banner updates these defaults with the visitor's choice, in either of two ways:
+
+```js
+// 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. In Europe, Google's tag waits half a second for that update before it sends anything.
+
+The event comes from [wagtail-cookie-consent](https://github.com/Limitless-Horizons/wagtail-cookie-consent), a companion package in development, but any banner can send it or call the function.
+
+## 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, unless the Django setting below supplies one. |
+| Deny analytics by default in Europe | On | The Europe defaults in [Consent](#consent). |
+| Site uses Google Ads | Off | When off, advertising signals are denied for every visitor. |
+| Track signed-in users | Off | When off, visits by signed-in users aren't tracked. |
+| Track email and phone links | On | Sends `contact_link_click` with `link_type` set to `email` or `phone`. |
+| Debug mode | Off | Sends events to Google Analytics' DebugView, for testing. |
+
+`WAGTAIL_GOOGLE_TAG_MEASUREMENT_ID` in your Django settings is a fallback, used by any site whose measurement ID is blank. It's useful for moving an existing tag over, or for setting the ID from an environment variable.
+
+### Testing your setup
+
+Turn on **Debug mode**, then visit your site in a private window, since your own signed-in visits aren't tracked. Your page views and events show up in Google Analytics under **Admin → DebugView**. Turn debug mode off when you're done.
+
+### Content Security Policy
+
+If your site has a Content Security Policy, allow Google's tag: `https://www.googletagmanager.com` in `script-src`, and Google Analytics' collection domains, such as `https://*.google-analytics.com`, in `connect-src`. The package itself uses no inline scripts.
+
+## 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.
+
+Some things are set in Google Analytics, not here:
+
+- How long data is kept (Google's default is two months)
+- Which events count as key events, such as `generate_lead`
+- Custom dimensions for your own parameters
+- Enhanced measurement: scrolls, outbound clicks, site search and the rest
+
+## Links
+
+- [Changelog](https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/CHANGELOG.md)
+- [Contributing](https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/CONTRIBUTING.md)
+- [Security policy](https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/SECURITY.md)
+
+## License
+
+BSD-3-Clause. See [LICENSE](https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/LICENSE).

wagtail_google_tag-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "wagtail-google-tag"
+version = "0.1.0"
+description = "Google tag (GA4) for Wagtail, set up in the Wagtail admin: per-site settings, Consent Mode defaults, page data and click events."
+readme = "README.md"
+license = "BSD-3-Clause"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Framework :: Wagtail",
+    "Framework :: Wagtail :: 7",
+    "Framework :: Wagtail :: 8",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "django>=5.2",
+    "wagtail>=7.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/Limitless-Horizons/wagtail-google-tag"
+Repository = "https://github.com/Limitless-Horizons/wagtail-google-tag"
+Changelog = "https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/README.md"
+Issues = "https://github.com/Limitless-Horizons/wagtail-google-tag/issues"
+
+[dependency-groups]
+dev = [
+    "dj-database-url>=3.1.2",
+    "pytest>=8.1.1",
+    "pytest-cov>=7.1.0",
+    "pytest-django>=4.12.0",
+    "ruff>=0.15.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.6,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "wagtail_google_tag"
+source-exclude = [
+    "wagtail_google_tag/static_src",
+    "wagtail_google_tag/test",
+    "testmanage.py",
+    ".*",
+    "prettier.config.js",
+    "*.json",
+    "*.ini",
+    "*.yml",
+]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "wagtail_google_tag.test.settings"
+testpaths = ["tests"]

wagtail_google_tag-0.1.0/pyproject.toml.orig

@@ -0,0 +1,75 @@
+[project]
+name = "wagtail-google-tag"
+version = "0.1.0"
+description = "Google tag (GA4) for Wagtail, set up in the Wagtail admin: per-site settings, Consent Mode defaults, page data and click events."
+readme = "README.md"
+license = "BSD-3-Clause"
+classifiers = [
+    # Update this based on your project's status.
+    # See: https://pypi.org/classifiers/
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Framework :: Wagtail",
+    "Framework :: Wagtail :: 7",
+    "Framework :: Wagtail :: 8",
+]
+# See: https://devguide.python.org/versions/#supported-versions
+requires-python = ">=3.11"
+dependencies = [
+    # https://www.djangoproject.com/download/#supported-versions
+    "django>=5.2",
+    # https://github.com/wagtail/wagtail/wiki/Release-schedule
+    # https://docs.wagtail.org/en/latest/releases/upgrading.html#compatible-django-python-versions
+    "wagtail>=7.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/Limitless-Horizons/wagtail-google-tag"
+Repository = "https://github.com/Limitless-Horizons/wagtail-google-tag"
+Changelog = "https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/Limitless-Horizons/wagtail-google-tag/blob/main/README.md"
+Issues = "https://github.com/Limitless-Horizons/wagtail-google-tag/issues"
+# Add funding link if needed.
+# Funding = "https://github.com/Limitless-Horizons/wagtail-google-tag"
+
+[dependency-groups]
+dev = [
+    "dj-database-url>=3.1.2",
+    "pytest>=8.1.1",
+    "pytest-cov>=7.1.0",
+    "pytest-django>=4.12.0",
+    "ruff>=0.15.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.6,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "wagtail_google_tag"
+source-exclude = [
+    "wagtail_google_tag/static_src",
+    "wagtail_google_tag/test",
+    "testmanage.py",
+    ".*",
+    "prettier.config.js",
+    "*.json",
+    "*.ini",
+    "*.yml",
+]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "wagtail_google_tag.test.settings"
+testpaths = ["tests"]

wagtail_google_tag-0.1.0/src/wagtail_google_tag/__init__.py

@@ -0,0 +1,2 @@
+VERSION = (0, 1, 0)
+__version__ = ".".join(map(str, VERSION))

wagtail_google_tag-0.1.0/src/wagtail_google_tag/apps.py

@@ -0,0 +1,12 @@
+from django.apps import AppConfig
+from django.utils.translation import gettext_lazy as _
+
+
+class WagtailGoogleTagAppConfig(AppConfig):
+    label = "wagtail_google_tag"
+    name = "wagtail_google_tag"
+    verbose_name = _("Google tag")
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        from . import checks  # noqa: F401

wagtail_google_tag-0.1.0/src/wagtail_google_tag/checks.py

@@ -0,0 +1,15 @@
+from django.apps import apps
+from django.core.checks import Error, register
+
+
+@register()
+def settings_app_installed(app_configs, **kwargs):
+    if apps.is_installed("wagtail.contrib.settings"):
+        return []
+    return [
+        Error(
+            "wagtail_google_tag needs wagtail.contrib.settings.",
+            hint='Add "wagtail.contrib.settings" to INSTALLED_APPS.',
+            id="wagtail_google_tag.E001",
+        )
+    ]

wagtail_google_tag-0.1.0/src/wagtail_google_tag/migrations/0001_initial.py

@@ -0,0 +1,101 @@
+# Generated by Django 5.2.19 on 2026-11-10 18:57
+
+import re
+
+import django.core.validators
+import django.db.models.deletion
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("wagtailcore", "0097_baselogentry_uuid_action_timestamp_indexes"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="GoogleTagSettings",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "measurement_id",
+                    models.CharField(
+                        blank=True,
+                        help_text="The GA4 measurement ID for this site, like G-A1B2C3D4E5. In Google Analytics, it's under Admin, Data streams. Leave it blank for no tag, unless the site's configuration supplies a default.",
+                        max_length=20,
+                        validators=[
+                            django.core.validators.RegexValidator(
+                                "^G-[A-Z0-9]+$",
+                                "Enter a GA4 measurement ID, like G-A1B2C3D4E5.",
+                                flags=re.RegexFlag["IGNORECASE"],
+                            )
+                        ],
+                        verbose_name="measurement ID",
+                    ),
+                ),
+                (
+                    "deny_analytics_in_europe",
+                    models.BooleanField(
+                        default=True,
+                        help_text="Visitors in the European Economic Area, the UK and Switzerland get no analytics cookies until they agree to them, for example through a consent banner.",
+                        verbose_name="deny analytics by default in Europe",
+                    ),
+                ),
+                (
+                    "uses_google_ads",
+                    models.BooleanField(
+                        default=False,
+                        help_text="When this is off, Google's advertising signals are denied for every visitor.",
+                        verbose_name="site uses Google Ads",
+                    ),
+                ),
+                (
+                    "track_signed_in_users",
+                    models.BooleanField(
+                        default=False,
+                        help_text="When this is off, visits by signed-in users, such as editors, are left out of the data.",
+                        verbose_name="track signed-in users",
+                    ),
+                ),
+                (
+                    "track_contact_links",
+                    models.BooleanField(
+                        default=True,
+                        help_text="Clicks on email and phone links send a contact_link_click event. The address or number itself is never sent.",
+                        verbose_name="track email and phone links",
+                    ),
+                ),
+                (
+                    "debug_mode",
+                    models.BooleanField(
+                        default=False,
+                        help_text="Sends events to DebugView in Google Analytics, for testing. Turn it off when you're done.",
+                        verbose_name="debug mode",
+                    ),
+                ),
+                (
+                    "site",
+                    models.OneToOneField(
+                        editable=False,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to="wagtailcore.site",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Google tag",
+                "verbose_name_plural": "Google tag",
+            },
+        ),
+    ]

wagtail_google_tag-0.1.0/src/wagtail_google_tag/models.py

@@ -0,0 +1,97 @@
+import re
+
+from django.core.validators import RegexValidator
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+from wagtail.admin.panels import FieldPanel, MultiFieldPanel
+from wagtail.contrib.settings.models import BaseSiteSetting, register_setting
+
+
+measurement_id_validator = RegexValidator(
+    r"^G-[A-Z0-9]+$",
+    _("Enter a GA4 measurement ID, like G-A1B2C3D4E5."),
+    flags=re.IGNORECASE,
+)
+
+
+@register_setting(icon="tag")
+class GoogleTagSettings(BaseSiteSetting):
+    measurement_id = models.CharField(
+        _("measurement ID"),
+        max_length=20,
+        blank=True,
+        validators=[measurement_id_validator],
+        help_text=_(
+            "The GA4 measurement ID for this site, like G-A1B2C3D4E5. In Google "
+            "Analytics, it's under Admin, Data streams. Leave it blank for no tag, "
+            "unless the site's configuration supplies a default."
+        ),
+    )
+    deny_analytics_in_europe = models.BooleanField(
+        _("deny analytics by default in Europe"),
+        default=True,
+        help_text=_(
+            "Visitors in the European Economic Area, the UK and Switzerland get no "
+            "analytics cookies until they agree to them, for example through a "
+            "consent banner."
+        ),
+    )
+    uses_google_ads = models.BooleanField(
+        _("site uses Google Ads"),
+        default=False,
+        help_text=_(
+            "When this is off, Google's advertising signals are denied for every "
+            "visitor."
+        ),
+    )
+    track_signed_in_users = models.BooleanField(
+        _("track signed-in users"),
+        default=False,
+        help_text=_(
+            "When this is off, visits by signed-in users, such as editors, are "
+            "left out of the data."
+        ),
+    )
+    track_contact_links = models.BooleanField(
+        _("track email and phone links"),
+        default=True,
+        help_text=_(
+            "Clicks on email and phone links send a contact_link_click event. The "
+            "address or number itself is never sent."
+        ),
+    )
+    debug_mode = models.BooleanField(
+        _("debug mode"),
+        default=False,
+        help_text=_(
+            "Sends events to DebugView in Google Analytics, for testing. Turn it "
+            "off when you're done."
+        ),
+    )
+
+    panels = [
+        FieldPanel("measurement_id"),
+        MultiFieldPanel(
+            [
+                FieldPanel("deny_analytics_in_europe"),
+                FieldPanel("uses_google_ads"),
+            ],
+            heading=_("Consent"),
+        ),
+        MultiFieldPanel(
+            [
+                FieldPanel("track_signed_in_users"),
+                FieldPanel("track_contact_links"),
+                FieldPanel("debug_mode"),
+            ],
+            heading=_("Tracking"),
+        ),
+    ]
+
+    class Meta:
+        verbose_name = _("Google tag")
+        verbose_name_plural = _("Google tag")
+
+    def save(self, *args, **kwargs):
+        self.measurement_id = self.measurement_id.strip().upper()
+        super().save(*args, **kwargs)

wagtail_google_tag-0.1.0/src/wagtail_google_tag/static/wagtail_google_tag/js/google-tag.js

@@ -0,0 +1,97 @@
+/**
+ * Wagtail Google tag: loads Google's tag with Consent Mode defaults, and
+ * defines window.wagtailGoogleTag:
+ *
+ * - track(name, params) sends an event.
+ * - consent({ analytics, marketing }) updates Consent Mode with a visitor's
+ *   choice. A "wagtail-cookie-consent:change" event on document, with the same
+ *   object as its detail, does the same.
+ *
+ * Both do nothing when the tag isn't loaded (no measurement ID, a preview, or
+ * a signed-in user who isn't tracked), so pages never need to check.
+ *
+ * Clicks on elements with data-google-tag-event send that event, with
+ * parameters from data-google-tag-params (JSON). Clicks on email and phone
+ * links send contact_link_click, unless the link has its own event.
+ */
+(() => {
+  if (window.wagtailGoogleTag) return;
+
+  const configElement = document.getElementById('wagtail-google-tag-config');
+  const config = configElement ? JSON.parse(configElement.textContent) : {};
+  const enabled = Boolean(config.id);
+
+  window.dataLayer = window.dataLayer || [];
+  function gtag() {
+    // Google's tag reads the arguments object itself, not an array.
+    window.dataLayer.push(arguments);
+  }
+
+  if (enabled) {
+    window.gtag = gtag;
+    config.consent.forEach((defaults) => gtag('consent', 'default', defaults));
+    gtag('js', new Date());
+    gtag('config', config.id, config.params);
+
+    const script = document.createElement('script');
+    script.async = true;
+    script.src = `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(config.id)}`;
+    document.head.appendChild(script);
+  }
+
+  const track = (name, params) => {
+    if (enabled && name) gtag('event', name, params || {});
+  };
+
+  const consent = (choice) => {
+    if (!enabled || !choice) return;
+    const update = {};
+    if ('analytics' in choice) {
+      update.analytics_storage = choice.analytics ? 'granted' : 'denied';
+    }
+    // Ad signals stay denied unless the site uses Google Ads.
+    if (config.ads && 'marketing' in choice) {
+      const value = choice.marketing ? 'granted' : 'denied';
+      update.ad_storage = value;
+      update.ad_user_data = value;
+      update.ad_personalization = value;
+    }
+    if (Object.keys(update).length) gtag('consent', 'update', update);
+  };
+
+  window.wagtailGoogleTag = { track, consent };
+
+  document.addEventListener('wagtail-cookie-consent:change', (event) => {
+    consent(event.detail);
+  });
+
+  const parseParams = (element) => {
+    const json = element.getAttribute('data-google-tag-params');
+    if (!json) return {};
+    try {
+      return JSON.parse(json);
+    } catch {
+      return {};
+    }
+  };
+
+  document.addEventListener('click', (event) => {
+    if (!enabled || !(event.target instanceof Element)) return;
+
+    const tagged = event.target.closest('[data-google-tag-event]');
+    if (tagged) {
+      track(tagged.getAttribute('data-google-tag-event'), parseParams(tagged));
+      return;
+    }
+
+    if (!config.contactLinks) return;
+    const link = event.target.closest('a[href]');
+    if (!link) return;
+    // No address or number is sent: GA forbids personal data.
+    if (link.protocol === 'mailto:') {
+      track('contact_link_click', { link_type: 'email' });
+    } else if (link.protocol === 'tel:') {
+      track('contact_link_click', { link_type: 'phone' });
+    }
+  });
+})();

wagtail_google_tag-0.1.0/src/wagtail_google_tag/tag.py

@@ -0,0 +1,113 @@
+"""
+What the {% google_tag %} template tag renders: whether Google's tag loads for
+this request, and the configuration the browser script gets.
+"""
+
+from django.conf import settings
+from django.utils.text import capfirst
+from wagtail.models import Page
+
+from .models import GoogleTagSettings
+
+
+# The European Economic Area (the EU, Iceland, Liechtenstein and Norway), the
+# UK and Switzerland, as ISO 3166-1 codes for Consent Mode's "region".
+EUROPE = (
+    # EU
+    "AT", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GR", "HR",
+    "HU", "IE", "IT", "LT", "LU", "LV", "MT", "NL", "PL", "PT", "RO", "SE", "SI",
+    "SK",
+    # Rest of the EEA
+    "IS", "LI", "NO",
+    # UK and Switzerland
+    "GB", "CH",
+)  # fmt: skip
+
+# How long Google's tag waits for a consent banner's update in Europe, in ms.
+WAIT_FOR_UPDATE = 500
+
+AD_SIGNALS = ("ad_storage", "ad_user_data", "ad_personalization")
+
+
+def get_settings(request):
+    """This site's settings, or the defaults when the request has no site."""
+    try:
+        return GoogleTagSettings.for_request(request)
+    except GoogleTagSettings.DoesNotExist:
+        return GoogleTagSettings()
+
+
+def get_measurement_id(site_settings):
+    """The site's measurement ID, or the WAGTAIL_GOOGLE_TAG_MEASUREMENT_ID
+    setting when the site has none."""
+    return site_settings.measurement_id or getattr(
+        settings, "WAGTAIL_GOOGLE_TAG_MEASUREMENT_ID", ""
+    )
+
+
+def default_page_params(page):
+    """The page_view parameters for a page without get_google_tag_params():
+    its page type as GA's content group."""
+    model = page.specific_class or type(page)
+    return {"content_group": str(capfirst(model._meta.verbose_name))}
+
+
+def page_params(page):
+    get_params = getattr(page, "get_google_tag_params", None)
+    if get_params is None:
+        return default_page_params(page)
+    return dict(get_params())
+
+
+def consent_defaults(site_settings):
+    """Consent Mode defaults: analytics granted, ad signals denied unless the
+    site uses Google Ads, and everything denied in Europe if the site says so.
+    Google applies the most specific region that matches the visitor."""
+    ads = "granted" if site_settings.uses_google_ads else "denied"
+    defaults = [{"analytics_storage": "granted", **dict.fromkeys(AD_SIGNALS, ads)}]
+    if site_settings.deny_analytics_in_europe:
+        defaults.append(
+            {
+                "analytics_storage": "denied",
+                **dict.fromkeys(AD_SIGNALS, "denied"),
+                "region": list(EUROPE),
+                "wait_for_update": WAIT_FOR_UPDATE,
+            }
+        )
+    return defaults
+
+
+def is_signed_in(request):
+    user = getattr(request, "user", None)
+    return bool(user and user.is_authenticated)
+
+
+def tag_config(context, overrides):
+    """The browser script's configuration. "id" is None when the tag doesn't
+    load: no measurement ID, a preview, or a signed-in user who isn't tracked."""
+    request = context.get("request")
+    if request is None:
+        return {"id": None}
+
+    site_settings = get_settings(request)
+    measurement_id = get_measurement_id(site_settings)
+    if (
+        not measurement_id
+        or getattr(request, "is_preview", False)
+        or (is_signed_in(request) and not site_settings.track_signed_in_users)
+    ):
+        return {"id": None}
+
+    page = context.get("page")
+    params = page_params(page) if isinstance(page, Page) else {}
+    params.update(overrides)
+    if site_settings.debug_mode:
+        params["debug_mode"] = True
+
+    return {
+        "id": measurement_id,
+        "consent": consent_defaults(site_settings),
+        "params": params,
+        "ads": site_settings.uses_google_ads,
+        "contactLinks": site_settings.track_contact_links,
+    }

wagtail_google_tag-0.1.0/src/wagtail_google_tag/templates/wagtail_google_tag/google_tag.html

@@ -0,0 +1,2 @@
+{% load static %}{{ config|json_script:"wagtail-google-tag-config" }}
+<script src="{% static 'wagtail_google_tag/js/google-tag.js' %}"></script>

wagtail_google_tag-0.1.0/src/wagtail_google_tag/templatetags/wagtail_google_tag.py

@@ -0,0 +1,15 @@
+from django import template
+
+from ..tag import tag_config
+
+
+register = template.Library()
+
+
+@register.inclusion_tag("wagtail_google_tag/google_tag.html", takes_context=True)
+def google_tag(context, **params):
+    """Google's tag, with Consent Mode defaults and the page's data, and the
+    window.wagtailGoogleTag script API. Keyword arguments add page_view
+    parameters, for templates without a Wagtail page:
+    {% google_tag content_group="Not found" %}."""
+    return {"config": tag_config(context, params)}