Capture pageviews on client-side navigation

[plusminushalf]

The problem

Docs pageviews look like they fell off a cliff in mid-June. They didn't — we stopped recording most of them.

	pageviews / week	sessions / week	pageviews per session
through early June	2,000–2,600	850–1,030	2.6
week of 14 June → now	730–1,200	850–1,050	1.1

Three things line up:

1. Sessions never moved. Same number of people, same visit pattern, before and after.
2. Pageviews per session collapsed to ~1.0 — every session now records only the page it lands on, and nothing the reader navigates to afterwards.
3. The posthog-js versions reporting before and after that week do not overlap at all. Everything before came from 1.369–1.380; everything after, from 1.393–1.433.

Vocs routes on the client, and PostHog's default capture_pageview fires on page load only. array.js is loaded unpinned from the CDN, so the version — and with it the effective behaviour — rolled forward without a deploy on our side.

Net effect: roughly 60% of docs pageviews have been missing for three months, and the "traffic drop" everyone has been looking at isn't real.

The fix

-posthog.init('phc_…', {api_host: 'https://docs.pimlico.io/ingest'})
+posthog.init('phc_…', {
+  api_host: 'https://docs.pimlico.io/ingest',
+  capture_pageview: 'history_change',
+})

'history_change' is PostHog's documented setting for single-page apps — it records route changes via the History API instead of only page loads. Setting it explicitly also means the behaviour stops depending on whichever array.js the CDN serves, which is what changed underneath us in the first place.

On the root cause

The data cannot distinguish between two explanations: PostHog's default changing in the newer SDK, or Vocs moving to client-side routing in the same dependency bump. They happened together and produce an identical signature. This fix is correct for either, but it's worth being clear that the mechanism is one of the two rather than confirmed as the first.

Verification

Cannot be confirmed before this deploys — it depends on the real SDK on the real site. After merge, expect pageviews per session to return to roughly 2.5 within a day. Query to check:

select toStartOfWeek(timestamp) as week,
       count() as pageviews,
       uniq(properties.$session_id) as sessions,
       round(count() / uniq(properties.$session_id), 2) as pv_per_session
from events
where event = '$pageview' and properties.$host = 'docs.pimlico.io'
  and timestamp > now() - interval 140 day
group by week order by week

Worth knowing when reading historical numbers: June–September docs pageviews are not comparable to anything before 14 June. Sessions are the reliable series across that boundary.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H92LZ24QZsspCiQgLjdEYB

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 21, 2026 10:04pm UTC