Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): download click-source attribution end to end (#2427)

Andrew Mikofalvy53890844a941
diff --git a/docs/src/app/continue/page.tsx b/docs/src/app/continue/page.tsx
index 14eeb7e57..320b2979a 100644
--- a/docs/src/app/continue/page.tsx
+++ b/docs/src/app/continue/page.tsx
@@ -9,7 +9,7 @@ import {
PENDING_SHARE_COOKIE,
PORT_PARAM,
} from '@/lib/deferred-share';
-import { DOWNLOAD_ROUTE } from '@/lib/site';
+import { downloadRouteForCta } from '@/lib/site';
export const dynamic = 'force-dynamic';
@@ -80,7 +80,7 @@ export default async function ContinuePage({ searchParams }: ContinuePageProps)
<br />
Don&rsquo;t have the app yet?{' '}
<a
- href={DOWNLOAD_ROUTE}
+ href={downloadRouteForCta('continue-page')}
className="font-medium text-slide-text underline underline-offset-4 transition-colors hover:text-primary"
>
Download it for macOS
diff --git a/docs/src/app/d/[encoded]/download/route.test.ts b/docs/src/app/d/[encoded]/download/route.test.ts
index 52f2c6a6f..5799d243a 100644
--- a/docs/src/app/d/[encoded]/download/route.test.ts
+++ b/docs/src/app/d/[encoded]/download/route.test.ts
@@ -9,11 +9,14 @@ type CaptureOpts = {
properties?: Record<string, string | undefined>;
};
let _lastCapture: CaptureOpts | null = null;
+let _isPrefetch = false;
mock.module('../../../../lib/track.ts', () => ({
captureServerEvent: (opts: CaptureOpts) => {
_lastCapture = opts;
},
resolveDistinctId: () => 'splash-1',
+ attribution: () => ({ referrer: 'openknowledge.ai', utm_content: 'should-be-overridden' }),
+ isPrefetchRequest: () => _isPrefetch,
}));
// Flip the decoded-share outcome per test.
@@ -45,7 +48,8 @@ describe('GET /d/[encoded]/download', () => {
expect(res.headers.get('set-cookie')).toContain('ok-pending-share=valid-share');
expect(_lastCapture?.event).toBe('dmg_downloaded');
expect(_lastCapture?.properties?.channel).toBe('stable');
- expect(_lastCapture?.properties?.source).toBe('share-splash');
+ // Server-authoritative: overrides the attribution() value.
+ expect(_lastCapture?.properties?.utm_content).toBe('share-splash');
expect(_lastCapture?.distinctId).toBe('splash-1');
});
@@ -57,7 +61,7 @@ describe('GET /d/[encoded]/download', () => {
expect(res.headers.get('location')).toBe(SPLASH_URL);
expect(res.headers.get('set-cookie')).toBeNull();
expect(_lastCapture?.event).toBe('dmg_downloaded');
- expect(_lastCapture?.properties?.source).toBe('share-splash');
+ expect(_lastCapture?.properties?.utm_content).toBe('share-splash');
});
test('unsupported-version share: no cookie, still counts', async () => {
@@ -68,4 +72,18 @@ describe('GET /d/[encoded]/download', () => {
expect(res.headers.get('set-cookie')).toBeNull();
expect(_lastCapture?.event).toBe('dmg_downloaded');
});
+
+ test('a prefetch still redirects (with cookie) but is NOT counted', async () => {
+ _viewKind = 'ok';
+ _lastCapture = null;
+ _isPrefetch = true;
+ try {
+ const res = await call('valid-share');
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(SPLASH_URL);
+ expect(_lastCapture).toBeNull();
+ } finally {
+ _isPrefetch = false;
+ }
+ });
});
diff --git a/docs/src/app/d/[encoded]/download/route.ts b/docs/src/app/d/[encoded]/download/route.ts
index 710e55f4d..0550f5fd6 100644
--- a/docs/src/app/d/[encoded]/download/route.ts
+++ b/docs/src/app/d/[encoded]/download/route.ts
@@ -1,7 +1,7 @@
import { NextResponse } from 'next/server';
import { buildPendingShareCookie } from '@/lib/deferred-share';
import { buildSplashViewModel, SPLASH_DOWNLOAD_URL } from '@/lib/share-splash';
-import { captureServerEvent, resolveDistinctId } from '@/lib/track';
+import { attribution, captureServerEvent, isPrefetchRequest, resolveDistinctId } from '@/lib/track';
/**
* `GET /d/<encoded>/download` — the splash Download CTA target.
@@ -25,11 +25,16 @@ export async function GET(
response.cookies.set(buildPendingShareCookie(encoded));
}
- captureServerEvent({
- event: 'dmg_downloaded',
- distinctId: resolveDistinctId(request),
- properties: { channel: 'stable', source: 'share-splash' },
- });
+ // A prefetch is not a download — redirect it, don't count it. `utm_content`
+ // is server-authoritative here (this route IS the share-splash CTA), so it
+ // wins over any `?utm_content=` on the request.
+ if (!isPrefetchRequest(request)) {
+ captureServerEvent({
+ event: 'dmg_downloaded',
+ distinctId: resolveDistinctId(request),
+ properties: { channel: 'stable', ...attribution(request), utm_content: 'share-splash' },
+ });
+ }
return response;
}
diff --git a/docs/src/app/d/[encoded]/splash-share-view.tsx b/docs/src/app/d/[encoded]/splash-share-view.tsx
index dc4834134..8cf953b58 100644
--- a/docs/src/app/d/[encoded]/splash-share-view.tsx
+++ b/docs/src/app/d/[encoded]/splash-share-view.tsx
@@ -5,7 +5,7 @@ import { SiteFooter } from '@/components/footer';
import { GitHubIcon } from '@/components/icons/github';
import { OkWordmark } from '@/components/ok-wordmark';
import { buildCloneCommand, SPLASH_INSTALL_COMMAND, type SplashView } from '@/lib/share-splash';
-import { DOWNLOAD_ROUTE } from '@/lib/site';
+import { downloadRouteForCta } from '@/lib/site';
import { SplashButtonLabel, splashPrimaryButton } from './splash-buttons';
import { SplashCliButton } from './splash-cli-button';
import { SplashCtaPanel } from './splash-cta-panel';
@@ -140,7 +140,7 @@ export function SplashFallback({ heading }: { heading: string }) {
</h1>
<div className="mt-10 flex flex-wrap items-center gap-4">
- <a href={DOWNLOAD_ROUTE} className={splashPrimaryButton}>
+ <a href={downloadRouteForCta('share-splash-fallback')} className={splashPrimaryButton}>
<SplashButtonLabel direction="down">DOWNLOAD FOR MAC</SplashButtonLabel>
</a>
<SplashCliButton installCommand={SPLASH_INSTALL_COMMAND} />
diff --git a/docs/src/app/download/beta/route.test.ts b/docs/src/app/download/beta/route.test.ts
index abf73d77d..21560e5c2 100644
--- a/docs/src/app/download/beta/route.test.ts
+++ b/docs/src/app/download/beta/route.test.ts
@@ -38,7 +38,8 @@ mock.module('../../../lib/track.ts', () => ({
_lastCapture = opts;
},
resolveDistinctId: () => 'visitor-9',
- referrerHostname: () => undefined,
+ attribution: () => ({ sec_fetch_site: 'none' }),
+ isPrefetchRequest: (request: Request) => request.headers.get('sec-purpose') === 'prefetch',
}));
// Dynamic import ensures route.ts imports the mocked modules above.
@@ -80,4 +81,17 @@ describe('GET /download/beta', () => {
expect(res.headers.get('cache-control')).toBe(FALLBACK_CACHE_CONTROL);
expect(_lastCapture).toBeNull();
});
+
+ test('a prefetch still redirects but is NOT counted', async () => {
+ _redirect = { kind: 'fresh', url: TEST_DMG_URL };
+ _lastCapture = null;
+ const res = await GET(
+ new Request('https://openknowledge.ai/download/beta', {
+ headers: { 'sec-purpose': 'prefetch' },
+ }),
+ );
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(TEST_DMG_URL);
+ expect(_lastCapture).toBeNull();
+ });
});
diff --git a/docs/src/app/download/beta/route.ts b/docs/src/app/download/beta/route.ts
index 6150c4bc9..e15151d15 100644
--- a/docs/src/app/download/beta/route.ts
+++ b/docs/src/app/download/beta/route.ts
@@ -1,5 +1,5 @@
import { createBetaResolver, toRedirectResponse } from '@/lib/download-links';
-import { captureServerEvent, referrerHostname, resolveDistinctId } from '@/lib/track';
+import { attribution, captureServerEvent, isPrefetchRequest, resolveDistinctId } from '@/lib/track';
/**
* Perennial beta-channel download URL: openknowledge.ai/download/beta
@@ -27,12 +27,13 @@ export async function GET(request: Request): Promise<Response> {
if (redirect.kind === 'fallback') {
console.error(`[download/beta] falling back to releases page: ${redirect.cause}`);
}
- // A fallback sends the user to the releases page, not a DMG — don't count it.
- if (redirect.kind !== 'fallback') {
+ // A fallback sends the user to the releases page, not a DMG, and a prefetch
+ // is not a click — don't count either.
+ if (redirect.kind !== 'fallback' && !isPrefetchRequest(request)) {
captureServerEvent({
event: 'dmg_downloaded',
distinctId: resolveDistinctId(request),
- properties: { channel: 'beta', referrer: referrerHostname(request) },
+ properties: { channel: 'beta', ...attribution(request) },
});
}
return toRedirectResponse(redirect);
diff --git a/docs/src/app/download/stable/route.test.ts b/docs/src/app/download/stable/route.test.ts
index 0e85796a4..667956405 100644
--- a/docs/src/app/download/stable/route.test.ts
+++ b/docs/src/app/download/stable/route.test.ts
@@ -15,7 +15,8 @@ mock.module('../../../lib/track.ts', () => ({
_lastCapture = opts;
},
resolveDistinctId: () => 'visitor-1',
- referrerHostname: () => 'news.ycombinator.com',
+ attribution: () => ({ referrer: 'news.ycombinator.com', utm_content: 'landing-hero' }),
+ isPrefetchRequest: (request: Request) => request.headers.get('sec-purpose') === 'prefetch',
}));
const { GET } = await import('./route.ts');
@@ -32,5 +33,18 @@ describe('GET /download/stable', () => {
expect(_lastCapture?.distinctId).toBe('visitor-1');
expect(_lastCapture?.properties?.channel).toBe('stable');
expect(_lastCapture?.properties?.referrer).toBe('news.ycombinator.com');
+ expect(_lastCapture?.properties?.utm_content).toBe('landing-hero');
+ });
+
+ test('a prefetch still redirects but is NOT counted', () => {
+ _lastCapture = null;
+ const res = GET(
+ new Request('https://openknowledge.ai/download/stable', {
+ headers: { 'sec-purpose': 'prefetch' },
+ }),
+ );
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(STABLE_DMG_URL);
+ expect(_lastCapture).toBeNull();
});
});
diff --git a/docs/src/app/download/stable/route.ts b/docs/src/app/download/stable/route.ts
index c112486a4..d2afb9f04 100644
--- a/docs/src/app/download/stable/route.ts
+++ b/docs/src/app/download/stable/route.ts
@@ -1,5 +1,5 @@
import { STABLE_DMG_URL } from '@/lib/download-links';
-import { captureServerEvent, referrerHostname, resolveDistinctId } from '@/lib/track';
+import { attribution, captureServerEvent, isPrefetchRequest, resolveDistinctId } from '@/lib/track';
/**
* Perennial stable-channel download URL: openknowledge.ai/download/stable
@@ -15,11 +15,14 @@ import { captureServerEvent, referrerHostname, resolveDistinctId } from '@/lib/t
export const dynamic = 'force-dynamic';
export function GET(request: Request): Response {
- captureServerEvent({
- event: 'dmg_downloaded',
- distinctId: resolveDistinctId(request),
- properties: { channel: 'stable', referrer: referrerHostname(request) },
- });
+ // A prefetch is not a download — redirect it, don't count it.
+ if (!isPrefetchRequest(request)) {
+ captureServerEvent({
+ event: 'dmg_downloaded',
+ distinctId: resolveDistinctId(request),
+ properties: { channel: 'stable', ...attribution(request) },
+ });
+ }
return new Response(null, {
status: 302,
headers: {
diff --git a/docs/src/app/updates/[channel]/[...path]/route.test.ts b/docs/src/app/updates/[channel]/[...path]/route.test.ts
index 7e4d550b5..0945b5aa7 100644
--- a/docs/src/app/updates/[channel]/[...path]/route.test.ts
+++ b/docs/src/app/updates/[channel]/[...path]/route.test.ts
@@ -12,6 +12,7 @@ mock.module('../../../../lib/track.ts', () => ({
_lastCapture = opts;
},
resolveDistinctId: () => 'updater-1',
+ userAgentProperties: () => ({ ua_class: 'electron' }),
}));
const BETA_DMG_URL =
@@ -69,6 +70,7 @@ describe('GET /updates/[channel]/[...path]', () => {
expect(_lastCapture?.properties?.artifact_type).toBe('zip');
expect(_lastCapture?.properties?.to_version).toBe('0.20.0');
expect(_lastCapture?.properties?.from_version).toBe('0.19.1');
+ expect(_lastCapture?.properties?.ua_class).toBe('electron');
});
test('beta zip parses the prerelease version and counts (no from_version header)', async () => {
@@ -81,6 +83,15 @@ describe('GET /updates/[channel]/[...path]', () => {
expect(_lastCapture?.properties?.from_version).toBeUndefined();
});
+ test('an ill-formed x-ok-from-version header is dropped, not forwarded to analytics', async () => {
+ _lastCapture = null;
+ const file = 'OpenKnowledge-0.20.0-arm64-mac.zip';
+ const res = await call('stable', [file], { 'x-ok-from-version': '../etc; rm -rf' });
+ expect(res.status).toBe(302);
+ expect(_lastCapture?.event).toBe('app_update_downloaded');
+ expect(_lastCapture?.properties?.from_version).toBeUndefined();
+ });
+
test('blockmap 302s but is NOT counted', async () => {
_lastCapture = null;
const file = 'OpenKnowledge-0.20.0-arm64-mac.zip.blockmap';
diff --git a/docs/src/app/updates/[channel]/[...path]/route.ts b/docs/src/app/updates/[channel]/[...path]/route.ts
index e47365964..d6dec6db8 100644
--- a/docs/src/app/updates/[channel]/[...path]/route.ts
+++ b/docs/src/app/updates/[channel]/[...path]/route.ts
@@ -1,11 +1,12 @@
import { createBetaResolver } from '@/lib/download-links';
-import { captureServerEvent, resolveDistinctId } from '@/lib/track';
+import { captureServerEvent, resolveDistinctId, userAgentProperties } from '@/lib/track';
/**
* Update-feed proxy: openknowledge.ai/updates/{stable,beta}/<asset>
*
- * electron-updater is pointed here (in a later desktop change) instead of at
- * GitHub directly, so updates can be counted per version. Every request is a
+ * electron-updater's feed points here instead of at GitHub directly (wired in
+ * the desktop app's auto-updater), so updates can be counted per version.
+ * Every request is a
* thin 302 to the byte-identical GitHub release asset — never re-hosted, so the
* manifest `sha512` and the macOS code signature both stay valid. Only the
* `*-mac.zip` (the artifact Squirrel.Mac swaps in) is counted as an update; the
@@ -106,6 +107,9 @@ export async function GET(
artifact_type: 'zip',
to_version: version,
from_version: rawFrom && FROM_VERSION.test(rawFrom) ? rawFrom : undefined,
+ // Confirms updates really come from electron-updater and surfaces any
+ // scraper/browser traffic hitting the update feed.
+ ...userAgentProperties(request),
},
});
}
diff --git a/docs/src/components/docs-sidebar-cta.tsx b/docs/src/components/docs-sidebar-cta.tsx
index 61f364fc2..d50da96c1 100644
--- a/docs/src/components/docs-sidebar-cta.tsx
+++ b/docs/src/components/docs-sidebar-cta.tsx
@@ -1,7 +1,7 @@
import { Download } from 'lucide-react';
import { GitHubIcon } from '@/components/icons/github';
import { MarketingButton } from '@/components/marketing-button';
-import { DOWNLOAD_ROUTE, GITHUB_URL } from '@/lib/site';
+import { downloadRouteForCta, GITHUB_URL } from '@/lib/site';
// Compact for the button label (e.g. "1.5K"); full comma-grouped for the tooltip.
const compactStars = new Intl.NumberFormat('en-US', {
@@ -18,14 +18,15 @@ const fullStars = new Intl.NumberFormat('en-US');
export function DocsSidebarCta({ stars }: { stars: number | null }) {
return (
<div className="flex gap-2">
- {/* MarketingButton (matches the docs Subscribe button). DOWNLOAD_ROUTE
- starts with /download/, so MarketingButton renders it as a raw <a>
- via its isRedirectRoute path — next/link never prefetches it, which
- would fire the 302 and inflate download counts. */}
+ {/* MarketingButton (matches the docs Subscribe button). The download
+ route starts with /download/, so MarketingButton renders it as a raw
+ <a> via its isRedirectRoute path — next/link never prefetches it,
+ which would fire the 302 and inflate download counts. rel omits
+ `noreferrer` so the same-origin Referer attributes the CTA. */}
<MarketingButton
- href={DOWNLOAD_ROUTE}
+ href={downloadRouteForCta('docs-sidebar')}
target="_blank"
- rel="noopener noreferrer"
+ rel="noopener"
aria-label="Download for macOS"
title="Download for macOS"
variant="primary"
diff --git a/docs/src/components/download-button.tsx b/docs/src/components/download-button.tsx
index 3b0dcfdbb..2e1aaa21c 100644
--- a/docs/src/components/download-button.tsx
+++ b/docs/src/components/download-button.tsx
@@ -1,23 +1,30 @@
import { DownloadIcon } from 'lucide-react';
-import { DOWNLOAD_ROUTE } from '@/lib/site';
+import type { DownloadCta } from '@/lib/site';
+import { downloadRouteForCta } from '@/lib/site';
type DownloadButtonProps = {
/** Defaults to the tracked stable-download route (fires `dmg_downloaded`). */
href?: string;
label?: string;
+ /** CTA slug reported as `utm_content` on `dmg_downloaded`. */
+ cta?: DownloadCta;
};
export function DownloadButton({
- href = DOWNLOAD_ROUTE,
+ href,
label = 'DOWNLOAD FOR MAC',
+ cta = 'docs-content',
}: DownloadButtonProps) {
// Raw <a>, not next/link: the download route is a 302 redirect handler, so
// next/link would prefetch it (firing the redirect) and double-fetch on click.
+ // rel intentionally omits `noreferrer`: the Referer carries the originating
+ // page, which is how the download event attributes to a docs page instead
+ // of counting as direct traffic.
return (
<a
- href={href}
+ href={href ?? downloadRouteForCta(cta)}
target="_blank"
- rel="noopener noreferrer"
+ rel="noopener"
className="not-prose my-4 inline-flex items-center gap-2 rounded-full bg-neutral-900 px-5 py-2.5 text-sm font-medium text-white shadow-sm transition-opacity hover:opacity-90 dark:bg-neutral-100 dark:text-neutral-900"
>
{label}
diff --git a/docs/src/lib/site.ts b/docs/src/lib/site.ts
index 68ba31675..e2117f4b6 100644
--- a/docs/src/lib/site.ts
+++ b/docs/src/lib/site.ts
@@ -78,4 +78,30 @@ export const DOWNLOAD_URL = STABLE_DMG_URL;
* CTAs and the `DownloadButton` link here so every download fires a
* `dmg_downloaded` event before the 302 to GitHub.
*/
-export const DOWNLOAD_ROUTE = '/download/stable';
+const DOWNLOAD_ROUTE = '/download/stable';
+
+/**
+ * Every internal download CTA slug this app mints, reported as
+ * `utm_content` on `dmg_downloaded`. Append-only: these are analytics
+ * lineage — renaming one orphans its dashboard history. Namespace:
+ * `docs-*` and share slugs here; `landing-*` belongs to ok-marketing.
+ * `share-splash` is minted server-side by the /d/[encoded]/download
+ * route rather than via downloadRouteForCta.
+ */
+export type DownloadCta =
+ | 'docs-content'
+ | 'docs-sidebar'
+ | 'continue-page'
+ | 'share-splash-fallback'
+ | 'share-splash';
+
+/**
+ * {@link DOWNLOAD_ROUTE} tagged with `?utm_content=<cta-slug>` so the download
+ * event attributes the exact CTA even when the browser sends no Referer.
+ * `utm_content` is the standard UTM field for differentiating links/CTAs;
+ * `utm_source`/`utm_medium` describe the acquisition channel and are reserved
+ * for genuinely external campaign links (see `attribution` in src/lib/track.ts).
+ */
+export function downloadRouteForCta(cta: DownloadCta): string {
+ return `${DOWNLOAD_ROUTE}?utm_content=${encodeURIComponent(cta)}`;
+}
diff --git a/docs/src/lib/track.test.ts b/docs/src/lib/track.test.ts
index 3e973bfa4..d53b5e205 100644
--- a/docs/src/lib/track.test.ts
+++ b/docs/src/lib/track.test.ts
@@ -1,9 +1,11 @@
import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
import {
+ attribution,
buildCapturePayload,
captureServerEvent,
- referrerHostname,
+ isPrefetchRequest,
resolveDistinctId,
+ userAgentProperties,
} from './track.ts';
const KEY = 'phc_test_key';
@@ -38,7 +40,8 @@ describe('buildCapturePayload', () => {
// privacy guards
expect(p.properties.$ip).toBeNull();
expect(p.properties.$geoip_disable).toBe(true);
- // never carries identifying request shape
+ // the builder never injects request-shape properties itself — routes opt
+ // in explicitly via userAgentProperties()
expect('$useragent' in p.properties).toBe(false);
});
});
@@ -80,15 +83,182 @@ describe('resolveDistinctId', () => {
});
});
-describe('referrerHostname', () => {
- test('returns hostname only (never the path)', () => {
- expect(referrerHostname(req({ referer: 'https://news.ycombinator.com/item?id=1' }))).toBe(
- 'news.ycombinator.com',
+function reqUrl(url: string, headers: Record<string, string> = {}): Request {
+ return new Request(url, { headers });
+}
+
+describe('attribution', () => {
+ test('captures utm_content from our own CTA links', () => {
+ const a = attribution(
+ reqUrl('https://openknowledge.ai/download/stable?utm_content=landing-hero'),
+ );
+ expect(a.utm_content).toBe('landing-hero');
+ });
+
+ test('captures the full standard UTM set from external campaign links', () => {
+ const a = attribution(
+ reqUrl(
+ 'https://openknowledge.ai/download/stable?utm_source=newsletter&utm_medium=email&utm_campaign=Launch%20Week&utm_content=header-button&utm_term=knowledge%20base',
+ ),
+ );
+ expect(a.utm_source).toBe('newsletter');
+ expect(a.utm_medium).toBe('email');
+ expect(a.utm_campaign).toBe('Launch Week');
+ expect(a.utm_content).toBe('header-button');
+ expect(a.utm_term).toBe('knowledge base');
+ });
+
+ test('sanitizes utm values: control chars stripped, length capped, empty dropped', () => {
+ const a = attribution(
+ reqUrl(
+ `https://openknowledge.ai/download/stable?utm_content=${'a'.repeat(150)}&utm_source=%00%01ok%7f&utm_medium=%20%20`,
+ ),
+ );
+ expect(a.utm_content).toBe('a'.repeat(100));
+ expect(a.utm_source).toBe('ok');
+ expect(a.utm_medium).toBeUndefined();
+ });
+
+ test('external referrer: hostname only, no path', () => {
+ const a = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', {
+ referer: 'https://news.ycombinator.com/item?id=1',
+ }),
+ );
+ expect(a.referrer).toBe('news.ycombinator.com');
+ expect(a.referrer_path).toBeUndefined();
+ });
+
+ test('missing or unparseable referer: no referrer properties', () => {
+ expect(
+ attribution(reqUrl('https://openknowledge.ai/download/stable')).referrer,
+ ).toBeUndefined();
+ const a = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', { referer: 'not a url' }),
+ );
+ expect(a.referrer).toBeUndefined();
+ expect(a.referrer_path).toBeUndefined();
+ });
+
+ test('own-site referrer: hostname plus page path, never the query string', () => {
+ const a = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', {
+ referer: 'https://openknowledge.ai/docs/get-started/quickstart?token=secret',
+ }),
+ );
+ expect(a.referrer).toBe('openknowledge.ai');
+ expect(a.referrer_path).toBe('/docs/get-started/quickstart');
+ });
+
+ test('own-site subdomain referrer also gets a path', () => {
+ const a = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', {
+ referer: 'https://www.openknowledge.ai/',
+ }),
+ );
+ expect(a.referrer_path).toBe('/');
+ });
+
+ test('own-site /d/<encoded> share referrer: hostname only, path suppressed', () => {
+ const a = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', {
+ referer: 'https://openknowledge.ai/d/aHR0cHM6Ly9naXRodWIuY29t',
+ }),
+ );
+ expect(a.referrer).toBe('openknowledge.ai');
+ expect(a.referrer_path).toBeUndefined();
+ });
+
+ test('own-site referrer path is capped at 200 chars', () => {
+ const a = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', {
+ referer: `https://openknowledge.ai/docs/${'x'.repeat(400)}`,
+ }),
+ );
+ expect(a.referrer_path?.length).toBe(200);
+ });
+
+ test('a lookalike domain is treated as external', () => {
+ const a = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', {
+ referer: 'https://notopenknowledge.ai/phish',
+ }),
+ );
+ expect(a.referrer).toBe('notopenknowledge.ai');
+ expect(a.referrer_path).toBeUndefined();
+ });
+
+ test('sec-fetch-site passes through only known values', () => {
+ const ok = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', { 'sec-fetch-site': 'cross-site' }),
+ );
+ expect(ok.sec_fetch_site).toBe('cross-site');
+ const junk = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', { 'sec-fetch-site': 'evil' }),
+ );
+ expect(junk.sec_fetch_site).toBeUndefined();
+ expect(
+ attribution(reqUrl('https://openknowledge.ai/download/stable')).sec_fetch_site,
+ ).toBeUndefined();
+ });
+
+ test('includes the user-agent properties', () => {
+ const a = attribution(
+ reqUrl('https://openknowledge.ai/download/stable', {
+ 'user-agent': 'Mozilla/5.0 (Macintosh) Safari/605.1.15',
+ }),
+ );
+ expect(a.$useragent).toBe('Mozilla/5.0 (Macintosh) Safari/605.1.15');
+ expect(a.ua_class).toBe('browser');
+ });
+});
+
+describe('userAgentProperties', () => {
+ const UA_URL = 'https://openknowledge.ai/download/stable';
+ function classify(ua: string): string | undefined {
+ return userAgentProperties(reqUrl(UA_URL, { 'user-agent': ua })).ua_class;
+ }
+
+ test('classifies browsers, bots, cli clients, and electron', () => {
+ expect(classify('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Safari/605.1.15')).toBe(
+ 'browser',
+ );
+ expect(classify('Mozilla/5.0 (compatible; Googlebot/2.1)')).toBe('bot');
+ expect(classify('Slackbot-LinkExpanding 1.0')).toBe('bot');
+ expect(classify('curl/8.4.0')).toBe('cli');
+ expect(classify('Wget/1.21')).toBe('cli');
+ expect(classify('electron-updater/6.3.0')).toBe('electron');
+ expect(
+ classify('Mozilla/5.0 OpenKnowledge/0.24.0 Chrome/128.0.0.0 Electron/32.1.0 Safari/537.36'),
+ ).toBe('electron');
+ expect(classify('SomethingUnrecognized/1.0')).toBe('other');
+ });
+
+ test('missing UA classifies as none with no $useragent', () => {
+ const p = userAgentProperties(reqUrl(UA_URL));
+ expect(p.ua_class).toBe('none');
+ expect(p.$useragent).toBeUndefined();
+ });
+
+ test('caps the raw UA length', () => {
+ const p = userAgentProperties(reqUrl(UA_URL, { 'user-agent': `Mozilla/${'x'.repeat(500)}` }));
+ expect(p.$useragent?.length).toBe(300);
+ });
+});
+
+describe('isPrefetchRequest', () => {
+ const ROUTE_URL = 'https://openknowledge.ai/download/stable';
+ test('true for browser and framework prefetch signals', () => {
+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { 'sec-purpose': 'prefetch' }))).toBe(true);
+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { 'sec-purpose': 'prefetch;prerender' }))).toBe(
+ true,
);
+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { purpose: 'prefetch' }))).toBe(true);
+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { 'next-router-prefetch': '1' }))).toBe(true);
});
- test('undefined when missing or unparseable', () => {
- expect(referrerHostname(req())).toBeUndefined();
- expect(referrerHostname(req({ referer: 'not a url' }))).toBeUndefined();
+ test('false for ordinary requests', () => {
+ expect(isPrefetchRequest(reqUrl(ROUTE_URL))).toBe(false);
+ expect(isPrefetchRequest(reqUrl(ROUTE_URL, { 'sec-fetch-site': 'none' }))).toBe(false);
});
});
diff --git a/docs/src/lib/track.ts b/docs/src/lib/track.ts
index 5853b511d..7606a8184 100644
--- a/docs/src/lib/track.ts
+++ b/docs/src/lib/track.ts
@@ -130,15 +130,165 @@ function readPosthogDistinctId(request: Request, key: string): string | null {
}
/**
- * Coarse referrer for the `referrer` property: hostname only, so a referring
- * path is never sent to PostHog. Missing or unparseable referer → omitted.
+ * The standard UTM campaign parameters, captured under their canonical names
+ * so PostHog's built-in UTM property definitions apply. Internal CTAs set only
+ * `utm_content` (the standard field for differentiating links/CTAs);
+ * `utm_source`/`utm_medium`/`utm_campaign` describe the acquisition channel
+ * and are reserved for genuinely external campaign links (newsletter, social)
+ * — fabricating them for internal clicks would corrupt campaign reporting.
*/
-export function referrerHostname(request: Request): string | undefined {
- const referer = request.headers.get('referer');
- if (!referer) return undefined;
+const UTM_PARAMS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'] as const;
+
+/**
+ * External campaign tools mint arbitrary UTM values, so no slug allowlist —
+ * just drop control characters and bound the length.
+ */
+function sanitizeUtmValue(raw: string | null): string | undefined {
+ if (!raw) return undefined;
+ const cleaned = [...raw]
+ .filter((ch) => ch.charCodeAt(0) >= 0x20 && ch.charCodeAt(0) !== 0x7f)
+ .join('')
+ .trim()
+ .slice(0, 100);
+ return cleaned.length > 0 ? cleaned : undefined;
+}
+
+const SEC_FETCH_SITE_VALUES = ['none', 'same-origin', 'same-site', 'cross-site'] as const;
+type SecFetchSite = (typeof SEC_FETCH_SITE_VALUES)[number];
+
+function isSecFetchSite(value: string): value is SecFetchSite {
+ return (SEC_FETCH_SITE_VALUES as readonly string[]).includes(value);
+}
+
+export type UaClass = 'browser' | 'bot' | 'cli' | 'electron' | 'none' | 'other';
+
+/**
+ * Path detail is captured for our own referring pages only — external
+ * referrers stay hostname-only.
+ */
+function isOwnSiteHostname(hostname: string): boolean {
+ return hostname === 'openknowledge.ai' || hostname.endsWith('.openknowledge.ai');
+}
+
+export interface AttributionProperties {
+ referrer?: string;
+ referrer_path?: string;
+ sec_fetch_site?: SecFetchSite;
+ utm_source?: string;
+ utm_medium?: string;
+ utm_campaign?: string;
+ utm_content?: string;
+ utm_term?: string;
+ $useragent?: string;
+ ua_class?: UaClass;
+}
+
+/**
+ * Attribution properties for a download event:
+ *
+ * - `utm_*` — standard campaign parameters, passed through under their
+ * canonical names. Our own CTAs tag links with `?utm_content=<cta-slug>`
+ * (immune to referrer stripping); external campaign links can use the full
+ * set and attribute with no custom vocabulary.
+ * - `referrer` / `referrer_path` — where the click came from. External sites
+ * report hostname only; the path is added for our own pages so an untagged
+ * link (e.g. pasted in docs prose) still attributes to the exact page.
+ * - `sec_fetch_site` — browser-supplied fetch classification (`none` = address
+ * bar / non-web entry, `same-origin`/`same-site` = our site, `cross-site` =
+ * external link, absent = non-browser client such as curl or a bot). This is
+ * what separates "pasted the URL from the README" from "clicked a link".
+ */
+export function attribution(request: Request): AttributionProperties {
+ const out: AttributionProperties = {};
+
try {
- return new URL(referer).hostname;
+ const params = new URL(request.url).searchParams;
+ for (const name of UTM_PARAMS) {
+ const value = sanitizeUtmValue(params.get(name));
+ if (value) out[name] = value;
+ }
} catch {
- return undefined;
+ // no UTM capture on an unparseable request URL
+ }
+
+ const referer = request.headers.get('referer');
+ if (referer) {
+ try {
+ const refUrl = new URL(referer);
+ // External referrers stay hostname-only; a referring path is only
+ // captured for our own pages, and never its query string. `/d/<encoded>`
+ // share routes are excluded outright — there the share payload (the
+ // encoded GitHub URL) lives in the PATH itself.
+ out.referrer = refUrl.hostname;
+ if (isOwnSiteHostname(refUrl.hostname) && !refUrl.pathname.startsWith('/d/')) {
+ out.referrer_path = refUrl.pathname.slice(0, 200);
+ }
+ } catch {
+ // unparseable referer → no referrer properties
+ }
+ }
+
+ const secFetchSite = request.headers.get('sec-fetch-site');
+ if (secFetchSite && isSecFetchSite(secFetchSite)) {
+ out.sec_fetch_site = secFetchSite;
}
+
+ Object.assign(out, userAgentProperties(request));
+
+ return out;
+}
+
+/**
+ * Client identity for downloads and updates. `$useragent` is the property
+ * PostHog's "User Agent Populator" transformation reads on server-captured
+ * events — with that transformation enabled on the project, ingestion derives
+ * `$browser`/`$browser_version` from it. `ua_class` is our own coarse,
+ * bounded bucket for dashboard grouping (browsers vs bots/unfurlers vs
+ * curl-style clients vs the Electron auto-updater) and needs no PostHog
+ * configuration. The UA is deliberately the only request-shape property we
+ * send — IP and geo stay suppressed (see buildCapturePayload).
+ */
+export function userAgentProperties(request: Request): {
+ $useragent?: string;
+ ua_class?: UaClass;
+} {
+ const ua = request.headers.get('user-agent');
+ if (!ua) return { ua_class: 'none' };
+ return { $useragent: ua.slice(0, 300), ua_class: classifyUserAgent(ua) };
+}
+
+/**
+ * Order matters: Electron and bot UAs both embed `Mozilla/5.0`, so the
+ * browser check must come last.
+ */
+function classifyUserAgent(ua: string): UaClass {
+ if (/electron-updater|electron-builder|\belectron\//i.test(ua)) return 'electron';
+ if (
+ /bot|crawler|spider|slurp|bingpreview|externalhit|embedly|whatsapp|telegram|slack|discord|pinterest|linkedin|vkshare/i.test(
+ ua,
+ )
+ ) {
+ return 'bot';
+ }
+ if (
+ /^curl|^wget|^httpie|python-requests|python-urllib|node-fetch|undici|axios|go-http-client|okhttp|java\/|libwww/i.test(
+ ua,
+ )
+ ) {
+ return 'cli';
+ }
+ if (ua.startsWith('Mozilla/')) return 'browser';
+ return 'other';
+}
+
+/**
+ * Browser and framework prefetches hit the download routes without a real
+ * click (Chrome sends `Sec-Purpose: prefetch`, Safari `Purpose: prefetch`,
+ * next/link `Next-Router-Prefetch: 1`). Counting them would inflate download
+ * numbers with phantom events — callers skip capture but still redirect.
+ */
+export function isPrefetchRequest(request: Request): boolean {
+ const purpose = request.headers.get('sec-purpose') ?? request.headers.get('purpose') ?? '';
+ if (/prefetch|prerender/i.test(purpose)) return true;
+ return request.headers.get('next-router-prefetch') !== null;
}