feat(analytics): record where paying customers actually came from

Adds first-party acquisition attribution and a sixteen-event funnel, written to this deployment's own database and read back on /admin/growth. Nothing is sent anywhere else, and the whole subsystem is off unless OPENFRAME_ENABLE_ANALYTICS is set, so a self-hosted instance carries the tables empty and pays nothing. The proxy gives a visitor an anonymous id and stores what brought them in two first-party cookies; signup copies that onto the account and claims the events the visitor produced before they had one, which is what joins the two halves of the funnel. Recording happens where each step actually happens rather than in the browser: an ad blocker cannot undercount landing views, and blocking rates differ by channel, so an undercounted denominator would have made GitHub traffic look like it converts better than it does. Every event carries a dedupe key on a UNIQUE column, so "recorded exactly once" is a property of the schema rather than of fifteen call sites. Subscription events are derived by comparing the row being overwritten with the row being written inside the existing Stripe sync, which makes them order-independent and replay-safe. The scoreboard reports step-to-step conversion with the denominator beside it, and splits by source over a rolling 28-day window rather than a week: at this volume a weekly per-source cell holds single digits, and a percentage computed from three visits reads exactly as confidently as one computed from three hundred. "How did you hear about us?" is asked on the first onboarding screen, not on the registration form. The number being measured is the signup conversion rate, and a question added to that form would move it.
2026-09-11 09:36:08 +00:00 · 2026-08-01 20:00:27 +03:00
parent 93e85683e9
commit 7ca5abd041
48 changed files with 3214 additions and 25 deletions
@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest';
+import {
+  classifyChannel,
+  extractReferrerHost,
+  normalizeHost,
+  sanitizeLandingPath,
+  sanitizeTag,
+} from '@/lib/analytics/channel';
+
+// Every expected value below is written by hand. Deriving them from the lookup
+// tables in the module would mean deleting an entry from a table also deletes
+// its own test case.
+
+describe('sanitizeTag', () => {
+  it('lowercases and trims', () => {
+    expect(sanitizeTag('  GitHub  ')).toBe('github');
+  });
+
+  it('rejects a tag carrying markup or control characters', () => {
+    expect(sanitizeTag('<script>')).toBeNull();
+    expect(sanitizeTag('news\nletter')).toBeNull();
+  });
+
+  it('caps the length at 64 characters', () => {
+    expect(sanitizeTag('a'.repeat(200))).toHaveLength(64);
+  });
+
+  it('treats an empty or non-string value as absent', () => {
+    expect(sanitizeTag('   ')).toBeNull();
+    expect(sanitizeTag(null)).toBeNull();
+    expect(sanitizeTag(undefined)).toBeNull();
+  });
+});
+
+describe('normalizeHost', () => {
+  it('drops the www prefix and the port', () => {
+    expect(normalizeHost('WWW.GitHub.com:443')).toBe('github.com');
+  });
+
+  it('rejects a value that is not a host', () => {
+    expect(normalizeHost('not a host')).toBeNull();
+    expect(normalizeHost('https://github.com')).toBeNull();
+  });
+});
+
+describe('extractReferrerHost', () => {
+  it('returns the host of a full referrer URL', () => {
+    expect(extractReferrerHost('https://news.ycombinator.com/item?id=1')).toBe(
+      'news.ycombinator.com'
+    );
+  });
+
+  it('drops the path and query, so a share token cannot be stored', () => {
+    expect(extractReferrerHost('https://example.com/share/[email protected]')).toBe(
+      'example.com'
+    );
+  });
+
+  it('ignores our own host, because that is a click inside the site', () => {
+    expect(extractReferrerHost('https://open-frame.net/pricing', 'open-frame.net')).toBeNull();
+    expect(extractReferrerHost('https://www.open-frame.net/pricing', 'open-frame.net')).toBeNull();
+  });
+
+  it('returns null for a missing or unparseable referrer', () => {
+    expect(extractReferrerHost(null)).toBeNull();
+    expect(extractReferrerHost('android-app://com.example')).toBeNull();
+  });
+});
+
+describe('sanitizeLandingPath', () => {
+  it('keeps the path and drops the query string', () => {
+    expect(sanitizeLandingPath('/vs/frameio')).toBe('/vs/frameio');
+  });
+
+  it('falls back to / for anything that is not a path', () => {
+    expect(sanitizeLandingPath('https://open-frame.net/x')).toBe('/');
+    expect(sanitizeLandingPath(null)).toBe('/');
+  });
+});
+
+describe('classifyChannel', () => {
+  it('is DIRECT with no tags and no referrer', () => {
+    expect(classifyChannel({})).toBe('DIRECT');
+  });
+
+  it('reads the referring host when there are no tags', () => {
+    expect(classifyChannel({ referrerHost: 'github.com' })).toBe('GITHUB');
+    expect(classifyChannel({ referrerHost: 'gist.github.com' })).toBe('GITHUB');
+    expect(classifyChannel({ referrerHost: 'youtu.be' })).toBe('YOUTUBE');
+    expect(classifyChannel({ referrerHost: 'www.producthunt.com' })).toBe('REVIEW_LINK');
+    expect(classifyChannel({ referrerHost: 'news.ycombinator.com' })).toBe('COMMUNITY');
+  });
+
+  it('treats every Google country domain as search', () => {
+    expect(classifyChannel({ referrerHost: 'google.com' })).toBe('GOOGLE');
+    expect(classifyChannel({ referrerHost: 'google.com.tr' })).toBe('GOOGLE');
+    expect(classifyChannel({ referrerHost: 'news.google.co.uk' })).toBe('GOOGLE');
+  });
+
+  it('does not mistake a lookalike domain for the real one', () => {
+    expect(classifyChannel({ referrerHost: 'notgithub.com' })).toBe('REFERRAL');
+    expect(classifyChannel({ referrerHost: 'google.com.evil.example' })).toBe('REFERRAL');
+  });
+
+  it('counts an unrecognised site that links to us as a referral', () => {
+    expect(classifyChannel({ referrerHost: 'someblog.example' })).toBe('REFERRAL');
+  });
+
+  it('prefers an explicit utm_source over the referring host', () => {
+    expect(classifyChannel({ utmSource: 'youtube', referrerHost: 'google.com' })).toBe('YOUTUBE');
+  });
+
+  it('reads a utm_source that was written as a domain', () => {
+    expect(classifyChannel({ utmSource: 'github.com' })).toBe('GITHUB');
+  });
+
+  it('files a tagged campaign we do not recognise as OTHER, not DIRECT', () => {
+    expect(classifyChannel({ utmSource: 'conference-flyer' })).toBe('OTHER');
+  });
+
+  it('lets the medium that names the motion win over the source that names the place', () => {
+    expect(classifyChannel({ utmSource: 'linkedin', utmMedium: 'outbound' })).toBe('OUTBOUND');
+    expect(classifyChannel({ utmSource: 'github', utmMedium: 'email' })).toBe('OUTBOUND');
+    expect(classifyChannel({ utmSource: 'someone', utmMedium: 'referral' })).toBe('REFERRAL');
+  });
+
+  it('ignores a source that fails sanitizing and falls back to the referrer', () => {
+    expect(classifyChannel({ utmSource: '<script>', referrerHost: 'youtube.com' })).toBe('YOUTUBE');
+  });
+});
@@ -0,0 +1,137 @@
+import { describe, it, expect } from 'vitest';
+import {
+  decodeFirstTouch,
+  encodeFirstTouch,
+  generateAnonymousId,
+  isAcquisitionChannel,
+  isValidAnonymousId,
+  type FirstTouch,
+} from '@/lib/analytics/cookies';
+import { isCountableDocumentRequest, isLikelyBot } from '@/lib/analytics/bots';
+
+const TOUCH: FirstTouch = {
+  channel: 'GITHUB',
+  utmSource: 'github',
+  utmMedium: 'readme',
+  utmCampaign: 'launch',
+  referrerHost: 'github.com',
+  landingPath: '/vs/frameio',
+};
+
+describe('first touch cookie', () => {
+  it('round-trips every field', () => {
+    expect(decodeFirstTouch(encodeFirstTouch(TOUCH))).toEqual(TOUCH);
+  });
+
+  it('round-trips a touch with nothing but a channel', () => {
+    const bare: FirstTouch = {
+      channel: 'DIRECT',
+      utmSource: null,
+      utmMedium: null,
+      utmCampaign: null,
+      referrerHost: null,
+      landingPath: '/',
+    };
+    expect(decodeFirstTouch(encodeFirstTouch(bare))).toEqual(bare);
+  });
+
+  it('rejects a hand-edited cookie carrying an unknown channel', () => {
+    const forged = encodeURIComponent(JSON.stringify({ c: 'INVESTOR_DEMO', p: '/' }));
+    expect(decodeFirstTouch(forged)).toBeNull();
+  });
+
+  it('re-sanitizes fields rather than trusting the cookie', () => {
+    const forged = encodeURIComponent(
+      JSON.stringify({ c: 'DIRECT', p: '/x', s: '<script>alert(1)</script>', r: 'not a host' })
+    );
+    const decoded = decodeFirstTouch(forged);
+    expect(decoded?.utmSource).toBeNull();
+    expect(decoded?.referrerHost).toBeNull();
+  });
+
+  it('returns null for garbage and for an absent cookie', () => {
+    expect(decodeFirstTouch('%%%not-json%%%')).toBeNull();
+    expect(decodeFirstTouch(null)).toBeNull();
+    expect(decodeFirstTouch(encodeURIComponent(JSON.stringify(['DIRECT'])))).toBeNull();
+  });
+});
+
+describe('anonymous id', () => {
+  it('generates an id the validator accepts', () => {
+    expect(isValidAnonymousId(generateAnonymousId())).toBe(true);
+  });
+
+  it('generates a different id each time', () => {
+    expect(generateAnonymousId()).not.toBe(generateAnonymousId());
+  });
+
+  it('rejects an id that is too short, too long or not base36', () => {
+    expect(isValidAnonymousId('abc')).toBe(false);
+    expect(isValidAnonymousId('a'.repeat(65))).toBe(false);
+    expect(isValidAnonymousId('ABCDEF0123456789ABCD')).toBe(false);
+    expect(isValidAnonymousId(undefined)).toBe(false);
+  });
+});
+
+describe('isAcquisitionChannel', () => {
+  it('accepts the nine buckets and nothing else', () => {
+    expect(isAcquisitionChannel('REVIEW_LINK')).toBe(true);
+    expect(isAcquisitionChannel('direct')).toBe(false);
+    expect(isAcquisitionChannel(7)).toBe(false);
+  });
+});
+
+describe('isLikelyBot', () => {
+  it('passes a real browser through', () => {
+    expect(
+      isLikelyBot(
+        'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126 Safari/537.36'
+      )
+    ).toBe(false);
+  });
+
+  it('catches crawlers, link previewers and scripts', () => {
+    expect(isLikelyBot('Googlebot/2.1 (+http://www.google.com/bot.html)')).toBe(true);
+    expect(isLikelyBot('facebookexternalhit/1.1')).toBe(true);
+    expect(isLikelyBot('curl/8.4.0')).toBe(true);
+    expect(isLikelyBot('python-requests/2.31.0')).toBe(true);
+    expect(isLikelyBot('HeadlessChrome/120.0.0.0')).toBe(true);
+  });
+
+  it('treats a missing user agent as a bot', () => {
+    expect(isLikelyBot('')).toBe(true);
+    expect(isLikelyBot(null)).toBe(true);
+  });
+});
+
+describe('isCountableDocumentRequest', () => {
+  it('counts a real page load', () => {
+    expect(isCountableDocumentRequest(new Headers({ 'sec-fetch-dest': 'document' }))).toBe(true);
+  });
+
+  it('does not count a prefetch of the register page', () => {
+    expect(
+      isCountableDocumentRequest(
+        new Headers({ 'sec-fetch-dest': 'document', 'sec-purpose': 'prefetch;prerender' })
+      )
+    ).toBe(false);
+    expect(
+      isCountableDocumentRequest(
+        new Headers({ 'sec-fetch-dest': 'document', 'next-router-prefetch': '1' })
+      )
+    ).toBe(false);
+  });
+
+  it('does not count an RSC navigation or a subresource', () => {
+    expect(
+      isCountableDocumentRequest(new Headers({ 'sec-fetch-dest': 'document', rsc: '1' }))
+    ).toBe(false);
+    expect(isCountableDocumentRequest(new Headers({ 'sec-fetch-dest': 'image' }))).toBe(false);
+  });
+
+  it('falls back to the accept header when fetch metadata is missing', () => {
+    expect(isCountableDocumentRequest(new Headers({ accept: 'text/html,*/*' }))).toBe(true);
+    expect(isCountableDocumentRequest(new Headers({ accept: 'application/json' }))).toBe(false);
+    expect(isCountableDocumentRequest(new Headers())).toBe(false);
+  });
+});
@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { conversionRates } from '@/lib/analytics/scoreboard';
+
+const WEEK = {
+  visitors: 200,
+  signups: 20,
+  firstVideo: 10,
+  shareLinks: 5,
+  externalFeedback: 1,
+  trials: 4,
+  newPaid: 1,
+};
+
+describe('conversionRates', () => {
+  it('divides each step by the one above it', () => {
+    const rates = conversionRates(WEEK);
+    expect(rates.visitorToSignup).toBeCloseTo(0.1);
+    expect(rates.signupToFirstVideo).toBeCloseTo(0.5);
+    expect(rates.firstVideoToShare).toBeCloseTo(0.5);
+    expect(rates.shareToFeedback).toBeCloseTo(0.2);
+    expect(rates.trialToPaid).toBeCloseTo(0.25);
+  });
+
+  it('returns null rather than zero when the denominator is zero', () => {
+    const rates = conversionRates({ ...WEEK, visitors: 0, trials: 0 });
+    expect(rates.visitorToSignup).toBeNull();
+    expect(rates.trialToPaid).toBeNull();
+    // "nobody arrived" and "nobody converted" are different facts, and the rest
+    // of the funnel still has to report normally.
+    expect(rates.signupToFirstVideo).toBeCloseTo(0.5);
+  });
+
+  it('reports a step where nobody converted as zero, not as missing', () => {
+    expect(conversionRates({ ...WEEK, newPaid: 0 }).trialToPaid).toBe(0);
+  });
+});
@@ -0,0 +1,163 @@
+// The proxy is where a visitor gets an identity, and it is the only place that
+// can: it runs on the edge, before the page, on every document request.
+//
+// The load-bearing detail below is that the id is written to the *request* as
+// well as the response. A cookie set only on the response is invisible to the
+// page rendering that same request, so the very first landing view, the one
+// carrying the campaign tags that brought the visitor, would go unrecorded.
+
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { NextRequest } from 'next/server';
+import { proxy } from '@/proxy';
+import { ANONYMOUS_ID_COOKIE, FIRST_TOUCH_COOKIE, decodeFirstTouch } from '@/lib/analytics/cookies';
+
+const BROWSER_UA =
+  'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126 Safari/537.36';
+
+function documentRequest(
+  url: string,
+  init?: { headers?: Record<string, string>; cookies?: Record<string, string> }
+) {
+  const headers = new Headers({
+    'user-agent': BROWSER_UA,
+    'sec-fetch-dest': 'document',
+    ...init?.headers,
+  });
+  const cookies = Object.entries(init?.cookies ?? {});
+  if (cookies.length > 0) {
+    headers.set('cookie', cookies.map(([name, value]) => `${name}=${value}`).join('; '));
+  }
+  return new NextRequest(new URL(url), { headers });
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe('proxy', () => {
+  it('always sets the content security policy', () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'false');
+
+    const response = proxy(documentRequest('https://open-frame.net/'));
+
+    expect(response.headers.get('Content-Security-Policy')).toContain("default-src 'self'");
+  });
+
+  it('sets no acquisition cookie at all when the flag is off', () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'false');
+
+    const response = proxy(documentRequest('https://open-frame.net/?utm_source=github'));
+
+    expect(response.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined();
+    expect(response.cookies.get(FIRST_TOUCH_COOKIE)).toBeUndefined();
+  });
+
+  it('gives a new visitor an id and stores what brought them', () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true');
+    const request = documentRequest(
+      'https://open-frame.net/?utm_source=youtube&utm_medium=video&utm_campaign=launch'
+    );
+
+    const response = proxy(request);
+
+    const id = response.cookies.get(ANONYMOUS_ID_COOKIE);
+    expect(id?.value).toMatch(/^[a-z0-9]{32}$/);
+    expect(id?.httpOnly).toBe(true);
+    expect(id?.sameSite).toBe('lax');
+    expect(id?.secure).toBe(true);
+
+    const touch = decodeFirstTouch(response.cookies.get(FIRST_TOUCH_COOKIE)?.value);
+    expect(touch).toEqual({
+      channel: 'YOUTUBE',
+      utmSource: 'youtube',
+      utmMedium: 'video',
+      utmCampaign: 'launch',
+      referrerHost: null,
+      landingPath: '/',
+    });
+
+    // The page rendering this same request has to be able to read both.
+    expect(request.cookies.get(ANONYMOUS_ID_COOKIE)?.value).toBe(id?.value);
+    expect(request.cookies.get(FIRST_TOUCH_COOKIE)?.value).toBeDefined();
+  });
+
+  it('classifies a visit that only carries a referrer', () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true');
+
+    const response = proxy(
+      documentRequest('https://open-frame.net/vs/frameio', {
+        headers: { referer: 'https://github.com/yusufipk/OpenFrame' },
+      })
+    );
+
+    expect(decodeFirstTouch(response.cookies.get(FIRST_TOUCH_COOKIE)?.value)).toMatchObject({
+      channel: 'GITHUB',
+      referrerHost: 'github.com',
+      landingPath: '/vs/frameio',
+    });
+  });
+
+  it('does not overwrite the first touch of a returning visitor', () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true');
+    const existingId = 'a1b2c3d4e5f60718293a4b5c6d7e8f90';
+
+    const response = proxy(
+      documentRequest('https://open-frame.net/?utm_source=google', {
+        cookies: { [ANONYMOUS_ID_COOKIE]: existingId, [FIRST_TOUCH_COOKIE]: 'anything' },
+      })
+    );
+
+    expect(response.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined();
+    expect(response.cookies.get(FIRST_TOUCH_COOKIE)).toBeUndefined();
+  });
+
+  it('replaces an id that does not look like one we issued', () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true');
+
+    const response = proxy(
+      documentRequest('https://open-frame.net/', {
+        cookies: { [ANONYMOUS_ID_COOKIE]: 'nope' },
+      })
+    );
+
+    expect(response.cookies.get(ANONYMOUS_ID_COOKIE)?.value).toMatch(/^[a-z0-9]{32}$/);
+  });
+
+  it('ignores crawlers, so they never enter the visitor count', () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true');
+
+    const response = proxy(
+      documentRequest('https://open-frame.net/', {
+        headers: { 'user-agent': 'Googlebot/2.1 (+http://www.google.com/bot.html)' },
+      })
+    );
+
+    expect(response.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined();
+  });
+
+  it('ignores a prefetch and an API call', () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true');
+
+    const prefetch = proxy(
+      documentRequest('https://open-frame.net/register', {
+        headers: { 'next-router-prefetch': '1' },
+      })
+    );
+    const api = proxy(
+      documentRequest('https://open-frame.net/api/projects', {
+        headers: { 'sec-fetch-dest': 'empty' },
+      })
+    );
+
+    expect(prefetch.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined();
+    expect(api.cookies.get(ANONYMOUS_ID_COOKIE)).toBeUndefined();
+  });
+
+  it('leaves the cookie insecure on plain http, so local development works', () => {
+    vi.stubEnv('OPENFRAME_ENABLE_ANALYTICS', 'true');
+
+    const response = proxy(documentRequest('http://localhost:3000/'));
+
+    expect(response.cookies.get(ANONYMOUS_ID_COOKIE)?.secure).toBe(false);
+  });
+});