plain-connect: add pageview tracking via {% connect_pageviews %}

davegaeddert · davegaeddert · commit ab468e6bf934 · 2026-05-19T10:37:48.000-05:00
Adds anonymous pageview analytics with optional signed-in user
attribution, injected with the {% connect_pageviews %} template tag and
reported to the pageview beacon endpoint.

The identity token encrypts the authenticated user's id (AES-256-GCM) so
the raw id never appears in page HTML; the user is read via
plain.auth.get_request_user(), with a lazy import so apps without
plain.auth still work. Includes a test suite covering identity
encryption and the rendered tag.

Also renames the stale PLAIN_CLOUD_EXPORT_ENABLED env var to
PLAIN_CONNECT_EXPORT_ENABLED.
diff --git a/example/.env.test b/example/.env.test
@@ -7,4 +7,4 @@ DEV_TUNNEL_URL=https://plain-example.plaintunnel.com
 # Keep tests from exporting telemetry to the real endpoint, even when
 # someone runs pytest directly against the example app without going
 # through scripts/test.
-PLAIN_CLOUD_EXPORT_ENABLED=false
+PLAIN_CONNECT_EXPORT_ENABLED=false
diff --git a/plain-connect/plain/connect/README.md b/plain-connect/plain/connect/README.md
@@ -6,6 +6,7 @@
 - [Settings](#settings)
 - [Sampling](#sampling)
 - [What gets exported](#what-gets-exported)
+- [Pageview tracking](#pageview-tracking)
 - [Observer coexistence](#observer-coexistence)
 - [FAQs](#faqs)
 - [Installation](#installation)
@@ -24,13 +25,16 @@ If `CONNECT_EXPORT_TOKEN` is not set, the package is a no-op — safe to install
 
 ## Settings
 
-| Setting                     | Default                               | Description                                                 |
-| --------------------------- | ------------------------------------- | ----------------------------------------------------------- |
-| `CONNECT_EXPORT_URL`        | `"https://ingest.plainframework.com"` | OTLP ingest endpoint (override to use a custom endpoint)    |
-| `CONNECT_EXPORT_TOKEN`      | `""`                                  | Auth token for the export endpoint                          |
-| `CONNECT_TRACE_SAMPLE_RATE` | `1.0`                                 | Probability of exporting a trace (0.0–1.0)                  |
-| `CONNECT_EXPORT_LOGS`       | `True`                                | Set to `False` to disable OTLP log export                   |
-| `CONNECT_LOG_LEVEL`         | `"INFO"`                              | Minimum severity exported via OTLP logs (level name or int) |
+| Setting                          | Default                               | Description                                                               |
+| -------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
+| `CONNECT_EXPORT_URL`             | `"https://ingest.plainframework.com"` | OTLP ingest endpoint (override to use a custom endpoint)                  |
+| `CONNECT_EXPORT_TOKEN`           | `""`                                  | Auth token for the export endpoint                                        |
+| `CONNECT_TRACE_SAMPLE_RATE`      | `1.0`                                 | Probability of exporting a trace (0.0–1.0)                                |
+| `CONNECT_EXPORT_LOGS`            | `True`                                | Set to `False` to disable OTLP log export                                 |
+| `CONNECT_LOG_LEVEL`              | `"INFO"`                              | Minimum severity exported via OTLP logs (level name or int)               |
+| `CONNECT_PAGEVIEWS_TOKEN`        | `""`                                  | Public pageview-endpoint token; enables the `{% connect_pageviews %}` tag |
+| `CONNECT_PAGEVIEWS_IDENTITY_KEY` | `""`                                  | Secret key for encrypting the logged-in user id into the identity token   |
+| `CONNECT_PAGEVIEWS_URL`          | `"https://beacon.plainframework.com"` | Pageview ingest endpoint                                                  |
 
 All settings can be set via `PLAIN_`-prefixed environment variables or in `app/settings.py`.
 
@@ -52,6 +56,34 @@ Metrics are not affected by sampling — histograms aggregate in-process and exp
 
 **Logs** — Records from the `plain` and `app` loggers, plus anything propagating to the root logger, are bridged into OTLP log records and exported with `trace_id` / `span_id` set from the active span. The minimum severity is controlled by `CONNECT_LOG_LEVEL` (default `INFO`); the root logger's level is widened to that floor when needed so libraries using `getLogger(__name__)` reach the exporter. To prevent feedback loops, two sources are skipped on the export path: the `opentelemetry` namespace, and any record emitted from inside the OTLP exporter's background thread (e.g. urllib3 connection errors raised by the exporter's own HTTP call). Your application's urllib3 logs are exported normally.
 
+## Pageview tracking
+
+plain.connect can track page views in your app — anonymous page-view analytics plus, optionally, attribution to your signed-in users. This is independent of the OTLP export above.
+
+Add the tag to your base template, just before `</body>`:
+
+```html
+{% connect_pageviews %}
+```
+
+Then set the public endpoint token:
+
+```
+PLAIN_CONNECT_PAGEVIEWS_TOKEN=plain_pv_...
+```
+
+The tag renders nothing until the token is set. Once enabled, it reports the URL, title, referrer, and a first-party anonymous id on each page load and SPA navigation (History `pushState` / back-forward).
+
+### User attribution
+
+To attribute pageviews to your signed-in users, also set the secret identity key:
+
+```
+PLAIN_CONNECT_PAGEVIEWS_IDENTITY_KEY=...
+```
+
+When set, the tag encrypts the signed-in user's id (AES-256-GCM) into an opaque token that only the pageview endpoint can decrypt — the raw id never appears in your HTML. The user is read from [plain.auth](../../plain-auth/plain/auth/README.md); apps without it (or anonymous visitors) are still counted, their pageviews simply carry no user id.
+
 ## Observer coexistence
 
 If [plain.observer](../../plain-observer/plain/observer/README.md) is also installed, both work simultaneously. plain.connect handles production export while observer provides the local dev toolbar and admin trace viewer. Observer detects the existing TracerProvider and layers its sampler and span processor on top.
diff --git a/plain-connect/plain/connect/assets/connect/pageviews.js b/plain-connect/plain/connect/assets/connect/pageviews.js
@@ -0,0 +1,71 @@
+(() => {
+  const script = document.currentScript;
+  if (!script) return;
+
+  // Guard against double-injection — patching pushState twice would
+  // multiply every navigation event.
+  if (window.__plainPageviews) return;
+  window.__plainPageviews = true;
+
+  const token = script.dataset.token;
+  const pageviewsUrl = script.dataset.pageviewsUrl;
+  if (!token || !pageviewsUrl) return;
+
+  const identity = script.dataset.identity || "";
+  const initialTraceId = script.dataset.traceId || "";
+
+  const ANONYMOUS_ID_KEY = "plain_pageviews_anonymous_id";
+
+  function anonymousId() {
+    try {
+      let id = localStorage.getItem(ANONYMOUS_ID_KEY);
+      if (!id) {
+        id = crypto.randomUUID();
+        localStorage.setItem(ANONYMOUS_ID_KEY, id);
+      }
+      return id;
+    } catch {
+      // localStorage unavailable (private mode, blocked storage, etc.)
+      return "";
+    }
+  }
+
+  const anonId = anonymousId();
+  let isInitialView = true;
+  let lastUrl = "";
+
+  function send() {
+    if (location.href === lastUrl) return;
+
+    const payload = {
+      token,
+      url: location.href,
+      title: document.title,
+      referrer: isInitialView ? document.referrer : lastUrl,
+      anonymous_id: anonId,
+      identity,
+      // Only the server-rendered initial load has a backend trace to link to.
+      trace_id: isInitialView ? initialTraceId : "",
+    };
+
+    lastUrl = location.href;
+    isInitialView = false;
+
+    try {
+      navigator.sendBeacon(pageviewsUrl, JSON.stringify(payload));
+    } catch {
+      // sendBeacon unsupported or blocked — drop the event.
+    }
+  }
+
+  send();
+
+  // SPA navigations: History pushState + back/forward.
+  const originalPushState = history.pushState;
+  history.pushState = function (...args) {
+    const result = originalPushState.apply(this, args);
+    setTimeout(send, 0);
+    return result;
+  };
+  window.addEventListener("popstate", () => setTimeout(send, 0));
+})();
diff --git a/plain-connect/plain/connect/default_settings.py b/plain-connect/plain/connect/default_settings.py
@@ -8,3 +8,11 @@
 # Minimum severity exported via OTLP logs. Accepts a level name ("INFO",
 # "DEBUG", ...) or the integer level value.
 CONNECT_LOG_LEVEL: str = "INFO"
+
+# Pageview tracking — injected via the {% connect_pageviews %} template tag.
+# Public endpoint token; safe to expose in page HTML.
+CONNECT_PAGEVIEWS_TOKEN: str = ""
+# Secret key for encrypting the logged-in user id into the identity token.
+CONNECT_PAGEVIEWS_IDENTITY_KEY: Secret[str] = ""
+# Pageview ingest endpoint.
+CONNECT_PAGEVIEWS_URL: str = "https://beacon.plainframework.com"
diff --git a/plain-connect/plain/connect/identity.py b/plain-connect/plain/connect/identity.py
@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+_NONCE_BYTES = 12
+
+
+def _derive_key(identity_key: str) -> bytes:
+    """Derive a 32-byte AES-256 key from the endpoint's identity_key.
+
+    A plain SHA-256 is sufficient (no salt/HKDF) because identity_key is a
+    high-entropy server-generated secret, not a user password. The beacon
+    Worker's decrypt must derive the key identically.
+    """
+    return hashlib.sha256(identity_key.encode()).digest()
+
+
+def encrypt_identity(user_id: int | str, identity_key: str) -> str:
+    """Encrypt a user id into an opaque token for the pageview beacon.
+
+    AES-256-GCM with a random nonce. The beacon endpoint decrypts it with the
+    same identity_key, so the raw user id never appears in page HTML. Returns
+    base64url(nonce + ciphertext + GCM tag).
+    """
+    key = _derive_key(identity_key)
+    nonce = os.urandom(_NONCE_BYTES)
+    ciphertext = AESGCM(key).encrypt(nonce, str(user_id).encode(), None)
+    return base64.urlsafe_b64encode(nonce + ciphertext).decode()
diff --git a/plain-connect/plain/connect/templates.py b/plain-connect/plain/connect/templates.py
@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+from jinja2.runtime import Context
+from opentelemetry import trace
+
+from plain.runtime import settings
+from plain.templates import register_template_extension
+from plain.templates.jinja.extensions import InclusionTagExtension
+
+from .identity import encrypt_identity
+
+
+@register_template_extension
+class ConnectPageviewsExtension(InclusionTagExtension):
+    tags = {"connect_pageviews"}
+    template_name = "connect/pageviews.html"
+
+    def get_context(
+        self, context: Context, *args: Any, **kwargs: Any
+    ) -> dict[str, Any]:
+        request = context.get("request")
+        token = settings.CONNECT_PAGEVIEWS_TOKEN
+        return {
+            "request": request,
+            "connect_pageviews_token": token,
+            "connect_pageviews_url": settings.CONNECT_PAGEVIEWS_URL,
+            "connect_pageviews_identity": _identity_token(request) if token else "",
+            "connect_pageviews_trace_id": _current_trace_id() if token else "",
+        }
+
+
+def _identity_token(request: Any) -> str:
+    identity_key = str(settings.CONNECT_PAGEVIEWS_IDENTITY_KEY)
+    if not identity_key or request is None:
+        return ""
+
+    # Plain stores the authenticated user off-request (keyed by the request
+    # object), reachable only via plain.auth. plain.connect doesn't depend on
+    # plain.auth, so an app without it simply has no identity to attribute.
+    try:
+        from plain.auth import get_request_user
+    except ImportError:
+        return ""
+
+    user = get_request_user(request)
+    if user is None:
+        return ""
+    return encrypt_identity(user.id, identity_key)
+
+
+def _current_trace_id() -> str:
+    span_context = trace.get_current_span().get_span_context()
+    if not span_context.trace_id:
+        return ""
+    return format(span_context.trace_id, "032x")
diff --git a/plain-connect/plain/connect/templates/connect/pageviews.html b/plain-connect/plain/connect/templates/connect/pageviews.html
@@ -0,0 +1 @@
+{% if connect_pageviews_token %}<script src="{{ asset('connect/pageviews.js') }}" data-token="{{ connect_pageviews_token }}" data-pageviews-url="{{ connect_pageviews_url }}" data-identity="{{ connect_pageviews_identity }}" data-trace-id="{{ connect_pageviews_trace_id }}" async nonce="{{ request.csp_nonce }}"></script>{% endif %}
diff --git a/plain-connect/pyproject.toml b/plain-connect/pyproject.toml
@@ -10,10 +10,11 @@ dependencies = [
   "plain>=0.113.0,<1.0.0",
   "opentelemetry-sdk>=1.34.1",
   "opentelemetry-exporter-otlp-proto-http>=1.34.1",
+  "cryptography>=42.0.0",
 ]
 
 [dependency-groups]
-dev = ["plain.pytest<1.0.0"]
+dev = ["plain.pytest<1.0.0", "plain.auth<1.0.0", "plain.assets<1.0.0", "plain.templates<1.0.0"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["plain"]
diff --git a/plain-connect/tests/app/settings.py b/plain-connect/tests/app/settings.py
@@ -0,0 +1,16 @@
+SECRET_KEY = "test"
+URLS_ROUTER = "app.urls.AppRouter"
+INSTALLED_PACKAGES = [
+    "plain.assets",
+    "plain.templates",
+    "plain.sessions",
+    "plain.auth",
+    "plain.postgres",
+    "plain.connect",
+    "app.users",
+]
+MIDDLEWARE = [
+    "plain.sessions.middleware.SessionMiddleware",
+    "plain.auth.middleware.AuthMiddleware",
+]
+AUTH_LOGIN_URL = "page"
diff --git a/plain-connect/tests/app/templates/page.html b/plain-connect/tests/app/templates/page.html
@@ -0,0 +1,6 @@
+<!doctype html>
+<html>
+  <body>
+    {% connect_pageviews %}
+  </body>
+</html>
diff --git a/plain-connect/tests/app/urls.py b/plain-connect/tests/app/urls.py
@@ -0,0 +1,15 @@
+from plain.assets.urls import AssetsRouter
+from plain.templates.views import TemplateView
+from plain.urls import Router, include, path
+
+
+class PageView(TemplateView):
+    template_name = "page.html"
+
+
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        include("assets", AssetsRouter),
+        path("", PageView, name="page"),
+    ]
diff --git a/plain-connect/tests/app/users/migrations/0001_initial.py b/plain-connect/tests/app/users/migrations/0001_initial.py
@@ -0,0 +1,18 @@
+from plain import postgres
+from plain.postgres import migrations
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="User",
+            fields=[
+                ("id", postgres.PrimaryKeyField()),
+                ("username", postgres.TextField(max_length=255)),
+            ],
+        ),
+    ]
diff --git a/plain-connect/tests/app/users/migrations/__init__.py b/plain-connect/tests/app/users/migrations/__init__.py
diff --git a/plain-connect/tests/app/users/models.py b/plain-connect/tests/app/users/models.py
@@ -0,0 +1,7 @@
+from plain import postgres
+from plain.postgres import types
+
+
+@postgres.register_model
+class User(postgres.Model):
+    username: str = types.TextField(max_length=255)
diff --git a/plain-connect/tests/public/test_identity.py b/plain-connect/tests/public/test_identity.py
@@ -0,0 +1,50 @@
+import base64
+import hashlib
+
+import pytest
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from plain.connect.identity import encrypt_identity
+
+IDENTITY_KEY = "endpoint-identity-secret"
+
+
+def _decrypt(token: str, identity_key: str) -> str:
+    """Independent inverse of encrypt_identity — proves the wire format.
+
+    The beacon Worker decrypts identically; this mirrors that logic rather
+    than reusing the encrypt-side code, so a format change can't pass silently.
+    """
+    key = hashlib.sha256(identity_key.encode()).digest()
+    raw = base64.urlsafe_b64decode(token)
+    nonce, ciphertext = raw[:12], raw[12:]
+    return AESGCM(key).decrypt(nonce, ciphertext, None).decode()
+
+
+def test_encrypt_identity_round_trips():
+    token = encrypt_identity(42, IDENTITY_KEY)
+    assert _decrypt(token, IDENTITY_KEY) == "42"
+
+
+def test_encrypt_identity_accepts_string_user_id():
+    token = encrypt_identity("user-abc", IDENTITY_KEY)
+    assert _decrypt(token, IDENTITY_KEY) == "user-abc"
+
+
+def test_encrypt_identity_uses_a_random_nonce():
+    # Same input twice must not produce the same token — otherwise the
+    # ciphertext would leak which page loads belong to the same user.
+    assert encrypt_identity(1, IDENTITY_KEY) != encrypt_identity(1, IDENTITY_KEY)
+
+
+def test_encrypt_identity_token_is_url_safe():
+    token = encrypt_identity(1, IDENTITY_KEY)
+    # Safe to drop straight into an HTML attribute / URL with no escaping.
+    assert token == base64.urlsafe_b64encode(base64.urlsafe_b64decode(token)).decode()
+
+
+def test_wrong_key_cannot_decrypt():
+    token = encrypt_identity(7, IDENTITY_KEY)
+    with pytest.raises(InvalidTag):
+        _decrypt(token, "the-wrong-key")
diff --git a/plain-connect/tests/public/test_pageviews.py b/plain-connect/tests/public/test_pageviews.py
diff --git a/scripts/pre-commit b/scripts/pre-commit
diff --git a/scripts/test b/scripts/test
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+{% if connect_pageviews_token %}<script src="{{ asset('connect/pageviews.js') }}" data-token="{{ connect_pageviews_token }}" data-pageviews-url="{{ connect_pageviews_url }}" data-identity="{{ connect_pageviews_identity }}" data-trace-id="{{ connect_pageviews_trace_id }}" async nonce="{{ request.csp_nonce }}"></script>{% endif %}`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,6 @@ @@
 +<!doctype html>
 +<html>
 +  <body>
 +    {% connect_pageviews %}
 +  </body>
 +</html>