Reader Engagement and Monetization Loop Design

Status: designed 2026-11-08, not built. Brainstormed with Jake; nothing is implemented. This page is the recovery point: a builder should be able to plan Project 1 from it without further conversation. Projects 2–4 are sketched and get their own short design pass when they come up, because real engagement data will sharpen them. Decision record: SA-17 on SimpleAgilityDecisionLog.

Search data (ContentIntelligenceDesign) tells us whether readers arrive. This design adds whether they got something once they were there — how long they actually read and what they did on the page — and turns that into three things: targeted content improvements, an honest view of what advertising costs readers, and a measured path from reader to signed-in contributor.

It is written for the whole Simple Agility stack: the collection pattern (Umami in the back-office suite, same-origin tracker, event vocabulary, batch read-back into product tables) applies to any product with readers, and Pressroom already follows most of it. Wikantik is the first product to close a content-improvement loop on top of it.

Why this exists and what success looks like

The question Jake wants answered for a page: did readers spend real time on it, and did they act on it — copy code, follow a link onward, interact with a diagram, sign in. Two pages with the same search traffic can be one that holds readers for six minutes with forty code copies and one that loses them in forty seconds. Those deserve different work:

Success is a backlog that can say "this page gets 300 visits a month, readers leave after 40 seconds, nobody copies its code, its summary is 22 characters and it was last verified 14 months ago" — one actionable sentence that only the product can produce, because half the facts live in the wiki — followed, 28 days after the rework, by a measured verdict on whether readers stayed longer and did more.

Traffic reality (recorded so nobody over-reads early numbers). As of 2026-11-08 the site-level traffic gate in Content Intelligence reads 426 against a required 5,000 (28-day impressions), and the August baseline was ~10 search clicks per 28 days. Per-page engagement numbers will be thin for a long time. That is why collection starts now (history cannot be created retroactively and collection is cheap) while the rules that act on it stay dormant behind gates (see Project 2).

Decisions made in the brainstorm (Jake's)

#Decision
D1Umami does all reader-behaviour measurement: reading time, on-page actions, the browser half of the sign-in funnel. No in-house browser collector.
D2This supersedes the in-wiki browser collector specified in the Content Intelligence spec (§7.6 "The browser collector", its telemetry_event/telemetry_page_daily tables, and the Phase 3 gate of ≥1,000 clicks/28 days). Its useful ideas are kept (below).
D3All traffic counts. Signed-in users, editors and Jake's own visits are not excluded or split out. No extra complexity there.
D4Ads stay even when they cost reading time; the response to a measured cost is to reduce ad frequency, not remove ads.
D5A consent banner is accepted as a necessity of AdSense, but it is not wanted: third-party surface is minimised — Umami for everything it can do, Google ads the only third party, because ads are the only thing that pays.
D6Signing in through SSO is the prized conversion — it is the path to editing, and a reader becoming an editor is the best outcome. There are no features driving it today; measure the existing trickle first.
D7A human stays in the loop. The backlog suggests; Jake hands the page to the content agent. No autonomous rework.
D8Recorded in the wiki as cross-cutting architecture, not only as a repository spec.

Decisions already binding this design (from the decision log)

Kept from the superseded Content Intelligence collector

Goals, non-goals, anti-goals

Goals

  1. Per page, per day: views, visitors, active reading time (median and p90), share reaching 75% scroll, and counts of each on-page action.
  2. Those facts joined with page state inside Wikantik, feeding two new opportunity rules and new outcome measures in effect evaluation.
  3. A sign-in funnel attributed to the page where it started.
  4. AdSense revenue with a frequency dial and a measured reading-time cost.

Non-goals (now)

Anti-goals — failure even if it technically works

Stack-level architecture (applies to every product with readers)

flowchart LR
    Reader["Reader's browser"] -->|"GET /analytics/script.js<br/>POST /analytics/api/send<br/>(same origin)"| Product["Product origin<br/>(Wikantik, Pressroom)"]
    Product -->|"LAN proxy"| Umami["Umami<br/>(back-office suite)"]
    Umami --- UDB[("Umami PostgreSQL<br/>raw events, 730-day retention")]
    Product -->|"batch read, own account<br/>(SA-16)"| Umami
    Product --- PT[("Product table<br/>per-page daily rollup (SA-1)")]
    Grafana["jakemon Grafana"] -.->|"grafana_ro view"| UDB

Conventions every product follows:

  1. Same-origin tracker. /analytics/script.js and /analytics/api/send on the product's own host, proxied over the LAN to the suite. CSP stays script-src 'self' / connect-src 'self'; ad blockers that block analytics hosts don't see a third-party host. The real client IP must reach Umami (Cloudflare's CF-Connecting-IP / X-Forwarded-For), or geography collapses to the proxy's address.
  2. Own account, own website. Each product instance is an Umami website; the product holds a non-admin Umami account from its configuration.
  3. Event vocabulary. Kebab-case event names; property names lower-snake; every event carries the product's stable page identifier (Wikantik: canonical_id) so numbers survive renames. Products declare their vocabulary on their design page (Wikantik's is below).
  4. Batch read-back, never in a request. A scheduled task reads Umami and replaces a product-owned rollup table, with connect/request timeouts; Umami being down means stale rollups and a logged warning, never a reader-facing error.
  5. Ads are the only allowed third-party script, and only on reader pages, behind geo-scoped consent (Project 4).

The four projects, in order

#ProjectDepends onState
1Reader instrumentation + engagement read-back (Wikantik)Umami reachable from the wiki; a suite-owned engagement view (cross-repo)Specified below — ready to plan
2Engagement opportunity rules + outcome measures (Content Intelligence)1, plus accumulated dataSketched
3Sign-in conversion funnel1Sketched
4AdSense with geo-scoped consent, frequency dial, ad-free holdout1 (for before/after reading data)Sketched

Ads come last on purpose: a clean pre-ads reading-time baseline is what makes their cost measurable.

Project 1 — Reader instrumentation and engagement read-back

Tracker delivery

Event vocabulary (Wikantik)

EventFires whenProperties
(page view)Page load and each SPA route change — Umami nativeurl path (native)
page-exitTab hidden (visibilitychange), pagehide, or SPA route change awaycanonical_id, cluster, active_s, max_scroll_pct
code-copyA code block's copy control is usedcanonical_id, lang
wikilink-clickAn internal wiki link is followedcanonical_id, target (target page's canonical id or slug)
outbound-clickAn external link is followedcanonical_id, dest (host only)
diagram-interactA rendered diagram or math block is clicked/expandedcanonical_id, kind (mermaid | plantuml | math)
toc-clickTable-of-contents entry usedcanonical_id
sign-in-click"Sign in" activatedcanonical_id (empty off-page)

Rules: cluster is the page's primary cluster. Property values come from page metadata or a fixed set, never from free page text. Keep within Umami's event-data limits for the pinned version (builder verifies counts/lengths).

Active time counts only while the page is visible and the reader has interacted (scroll, key, pointer) within the last 30 seconds — 30 s is my call; tune if data says otherwise. page-exit fires once per page visit; a page visit that ends without it (crash, killed tab) is an accepted loss. Delivery on pagehide is the known fragile point — the builder verifies the pinned tracker's send survives page unload (keepalive/beacon) and, if not, sends that one event with a beacon to the same endpoint.

Read-back into Wikantik

Minimal read surface for Project 1

Engagement columns per page on the existing Content Intelligence admin panel (/admin/insights), and the same facts available to agents through the existing admin MCP read path (exact tool shape left to the builder, following the existing list_content_opportunities evidence style). Nothing acts on the data yet.

Privacy disclosure

PrivacyPolicy (and TermsOfService if it mentions analytics) gains a plain statement: cookieless, self-hosted analytics; what is measured (pages, reading time, the actions above); no personal profile; retention 730 days for raw events, permanent per-page daily totals. This is a content operation on production through the admin MCP (prod is authoritative for content), made in the same release that switches the tracker on; mirror it into docs/wikantik-pages/ afterwards.

Project 1 is done when

Project 2 — Engagement rules and outcome measures (sketch)

Project 3 — Sign-in conversion funnel (sketch)

  1. sign-in-click (browser, Umami, carries the starting page's canonical_id).
  2. SSO completed — recorded server-side (cannot be blocked or forged by a browser), split first-time vs returning, attributed to the page the reader returns to after login.
  3. First edit — recorded server-side (Wikantik already records edits and logins; the builder decides whether the funnel reads those existing records or writes a dedicated one).

Credit goes to the starting page, giving a "pages that make contributors" list distinct from "pages that hold attention". Open for its own pass: where the server-side steps land (product table vs Umami server-side event), and how the return-to page is carried through the SSO round-trip.

Project 4 — AdSense (sketch)

Where each piece of data lives (SA-1 test)

DataLives inWhy
Raw page views and eventsUmami (back-office suite)Observation; the suite owns retention
Per-page daily engagement rollupWikantik reader_engagement_dailyFunctional input to opportunity ranking and effect measurement
Sign-in funnel server stepsWikantik (Project 3 decides table)Functional input to ranking "pages that make contributors"
Dashboards over raw trafficGrafana via suite-owned grafana_ro viewObservation
AdSense revenuejakemon feed (Project 4)Third-party source (SA-16)

Left to the builder

The /analytics/* proxy mechanism (within the constraints above); the Umami API calls and paging; the exact rollup column names; the scheduler cadence beyond "at least nightly"; the admin-panel layout; how the frontend attaches event handlers (delegated listeners vs per-component); the website registration mechanism (configured id, or a Pressroom-style reconcile against Umami's API).

Resuming this work

  1. Read this page, then SimpleAgilityBackOfficeSuite (Umami's home and client contract) and ContentIntelligenceDesign (the loop this extends).
  2. Check where Umami runs. As of 2026-11-08 it is live inside Pressroom's deployment on docker1 (docker-compose.backoffice.yml in the Pressroom repo), with the move to the suite on docker2 specified but not confirmed done; there is no Wikantik website or account in it yet, and no dev/test Umami for Wikantik's ITs. Project 1's code works against Umami wherever it runs (the target is configuration), so build and test against a stub, and make "Umami reachable from docker1 with a wikantik account, website and the engagement view" the gating milestone for production verification. An in-wiki proxy works against either location; a tunnel path rule depends on the suite's Caddy accepting the wiki host — weigh that when choosing.
  3. Start a Wikantik session with get_briefing(clusters=["wikantik-development"], prompt="reader engagement Project 1") and plan Project 1.

See also