ValTown Project Analytics

Reusable event ingest and browser client for lightweight analytics across multiple Val Town projects.

Endpoints

GET  /client.js\nPOST /track\nGET  /summary?project=guess-that-hype\nGET  /events?project=guess-that-hype&limit=25

Quick Start

<script src=\"${origin}/client.js\" defer></script>\n<script defer>\n  window.addEventListener(\"DOMContentLoaded\", function () {\n    const analytics = window.ValTownAnalytics.init({\n      endpoint: \"${origin}/track\",\n      project: \"my-project\",\n    });\n\n    analytics.track(\"page_ready\", { area: \"landing\" });\n  });\n</script>

\n \n`;\n}\n\nfunction clientJs(origin: string) {\n return `(function () {\n var STORAGE_KEY = \"vt_project_analytics_session_v1\";\n var state = {\n endpoint: ${JSON.stringify(origin + \"/track\")},\n project: \"\",\n globalProps: {},\n sessionId: null,\n debug: false,\n };\n\n function randomId() {\n if (window.crypto && window.crypto.randomUUID) {\n return window.crypto.randomUUID();\n }\n return \"vt-\" + Date.now().toString(36) + \"-\" + Math.random().toString(36).slice(2, 10);\n }\n\n function getSessionId() {\n if (state.sessionId) return state.sessionId;\n try {\n var existing = window.localStorage.getItem(STORAGE_KEY);\n if (existing) {\n state.sessionId = existing;\n return existing;\n }\n var created = randomId();\n window.localStorage.setItem(STORAGE_KEY, created);\n state.sessionId = created;\n return created;\n } catch (_error) {\n state.sessionId = randomId();\n return state.sessionId;\n }\n }\n\n function send(payload) {\n var body = JSON.stringify(payload);\n if (state.debug) console.log(\"[ValTownAnalytics]\", payload);\n if (navigator.sendBeacon && body.length < 60000) {\n var blob = new Blob([body], { type: \"application/json\" });\n if (navigator.sendBeacon(state.endpoint, blob)) return Promise.resolve(true);\n }\n return fetch(state.endpoint, {\n method: \"POST\",\n headers: { \"content-type\": \"application/json\" },\n body: body,\n keepalive: true,\n mode: \"cors\",\n }).then(function () { return true; }).catch(function () { return false; });\n }\n\n function track(event, props) {\n if (!state.project || !event) return Promise.resolve(false);\n return send({\n project: state.project,\n event: event,\n sessionId: getSessionId(),\n pagePath: window.location.pathname,\n pageUrl: window.location.href,\n referrer: document.referrer || null,\n source: \"browser\",\n ts: new Date().toISOString(),\n props: Object.assign({}, state.globalProps, props || {}),\n });\n }\n\n window.ValTownAnalytics = {\n init: function init(config) {\n config = config || {};\n state.endpoint = config.endpoint || state.endpoint;\n state.project = config.project || state.project;\n state.globalProps = config.globalProps || {};\n state.debug = Boolean(config.debug);\n getSessionId();\n return {\n track: track,\n sessionId: function () { return getSessionId(); },\n };\n },\n track: track,\n };\n})();`;\n}\n\nfunction safeString(value: unknown, max = 255) {\n if (typeof value !== \"string\") return null;\n const trimmed = value.trim();\n if (!trimmed) return null;\n return trimmed.slice(0, max);\n}\n\nfunction safeProps(value: unknown) {\n if (!value || typeof value !== \"object\" || Array.isArray(value)) return {};\n const jsonValue = JSON.stringify(value);\n if (!jsonValue) return {};\n if (jsonValue.length <= 6000) return value;\n return { truncated: true, preview: jsonValue.slice(0, 5900) };\n}\n\nfunction eventId() {\n return crypto.randomUUID();\n}\n\nasync function ingest(req: Request) {\n await ensureSchema();\n\n let body: any;\n try {\n body = await req.json();\n } catch {\n return json({ ok: false, error: \"invalid_json\" }, { status: 400 });\n }\n\n const project = safeString(body?.project, 120);\n const event = safeString(body?.event, 120);\n if (!project || !event) {\n return json({ ok: false, error: \"project_and_event_required\" }, { status: 400 });\n }\n\n const props = safeProps(body?.props);\n await sqlite.execute({\n sql: `INSERT INTO events (\n id, project, event, session_id, page_path, page_url, referrer, source, user_agent, ts, props_json\n ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n args: [\n eventId(),\n project,\n event,\n safeString(body?.sessionId, 120),\n safeString(body?.pagePath, 500),\n safeString(body?.pageUrl, 1000),\n safeString(body?.referrer, 1000),\n safeString(body?.source, 60),\n safeString(req.headers.get(\"user-agent\"), 500),\n safeString(body?.ts, 64) || new Date().toISOString(),\n JSON.stringify(props),\n ],\n });\n\n return json({ ok: true });\n}\n\nasync function summary(project: string) {\n await ensureSchema();\n const totals = await sqlite.execute({\n sql: `SELECT event, COUNT(*) AS count FROM events WHERE project = ? GROUP BY event ORDER BY count DESC, event ASC`,\n args: [project],\n });\n const latest = await sqlite.execute({\n sql: `SELECT ts, event, props_json FROM events WHERE project = ? ORDER BY ts DESC LIMIT 10`,\n args: [project],\n });\n const sessions = await sqlite.execute({\n sql: `SELECT COUNT(DISTINCT session_id) AS count FROM events WHERE project = ?`,\n args: [project],\n });\n\n return {\n project,\n uniqueSessions: sessions.rows?.[0]?.count ?? 0,\n events: totals.rows ?? [],\n latest: (latest.rows ?? []).map((row: any) => ({\n ts: row.ts,\n event: row.event,\n props: JSON.parse(row.props_json || \"{}\"),\n })),\n };\n}\n\nasync function recentEvents(project: string, limit: number) {\n await ensureSchema();\n const rows = await sqlite.execute({\n sql: `SELECT ts, event, session_id, page_path, props_json FROM events WHERE project = ? ORDER BY ts DESC LIMIT ?`,\n args: [project, limit],\n });\n return (rows.rows ?? []).map((row: any) => ({\n ts: row.ts,\n event: row.event,\n sessionId: row.session_id,\n pagePath: row.page_path,\n props: JSON.parse(row.props_json || \"{}\"),\n }));\n}\n\nexport default async function handler(req: Request): Promise {\n const url = new URL(req.url);\n const origin = url.origin;\n\n if (req.method === \"OPTIONS\") {\n return new Response(null, { status: 204, headers: CORS_HEADERS });\n }\n\n if (req.method === \"GET\" && url.pathname === \"/\") {\n return html(pageHtml(origin));\n }\n\n if (req.method === \"GET\" && url.pathname === \"/client.js\") {\n return javascript(clientJs(origin));\n }\n\n if (req.method === \"POST\" && url.pathname === \"/track\") {\n return ingest(req);\n }\n\n if (req.method === \"GET\" && url.pathname === \"/summary\") {\n const project = safeString(url.searchParams.get(\"project\"), 120);\n if (!project) return json({ ok: false, error: \"project_required\" }, { status: 400 });\n return json(await summary(project));\n }\n\n if (req.method === \"GET\" && url.pathname === \"/events\") {\n const project = safeString(url.searchParams.get(\"project\"), 120);\n const limit = Math.min(Number(url.searchParams.get(\"limit\") || 25), 100);\n if (!project) return json({ ok: false, error: \"project_required\" }, { status: 400 });\n return json({ project, events: await recentEvents(project, limit) });\n }\n\n return json({ ok: false, error: \"not_found\" }, { status: 404 });\n}\n","label",[60],"2ec9dcca-239a-11f1-972d-42dde27851f2",["D",1773928054187],"# ValTown Project Analytics\n\nPublic Val Town analytics service:\n- https://www.val.town/x/pchinjr/valtown_project_analytics\n\nLive service:\n- https://pchinjr--2dfdceb4239511f1baa142dde27851f2.web.val.run\n\n## Overview\n\n`valtown_project_analytics` is a reusable analytics service for lightweight event tracking across multiple Val Town projects.\n\nIt provides:\n- a browser client script you can drop into any Val Town app\n- an ingest endpoint for event writes\n- simple JSON reporting endpoints for summaries and recent events\n- shared storage using Val Town global SQLite\n\nThis is intentionally small and pragmatic. It is meant for meaningful product events, not full session replay or enterprise analytics workflows.\n\n## Routes\n\n- `GET /`\n Human-readable landing page with usage notes\n- `GET /client.js`\n Reusable browser client\n- `POST /track`\n Event ingest endpoint\n- `GET /summary?project=`\n Per-project summary with unique sessions, totals, and recent events\n- `GET /events?project=&limit=25`\n Recent per-project event stream\n- `OPTIONS *`\n CORS preflight handling\n\n## Data Model\n\nEvents are stored in a shared SQLite table named `events`.\n\nColumns:\n- `id`\n- `project`\n- `event`\n- `session_id`\n- `page_path`\n- `page_url`\n- `referrer`\n- `source`\n- `user_agent`\n- `ts`\n- `received_at`\n- `props_json`\n\nIndexes:\n- `idx_events_project_ts`\n- `idx_events_project_event_ts`\n\n## Browser Integration\n\n```html\n\n\n```\n\n## Client API\n\n`window.ValTownAnalytics.init(config)` accepts:\n- `project`\n- `endpoint` optional override\n- `globalProps` optional object merged into every event\n- `debug` optional boolean\n\nIt returns:\n- `track(event, props)`\n- `sessionId()`\n\nBehavior:\n- generates and persists a browser session id in `localStorage`\n- uses `navigator.sendBeacon` when available\n- falls back to `fetch` with `keepalive`\n\n## Event Shape\n\n```json\n{\n \"project\": \"guess-that-hype\",\n \"event\": \"quiz_started\",\n \"sessionId\": \"vt-...\",\n \"pagePath\": \"/\",\n \"pageUrl\": \"https://example.web.val.run/\",\n \"referrer\": \"https://example.com/\",\n \"source\": \"browser\",\n \"ts\": \"2026-03-19T13:00:00.000Z\",\n \"props\": {\n \"runId\": \"...\",\n \"questionsPerRun\": 8\n }\n}\n```\n\n## Recommended Metrics\n\n- `page_viewed`\n- `quiz_started`\n- `question_answered`\n- `quiz_completed`\n- `share_clicked`\n- `share_copied`\n- `cta_clicked`\n\n## Tradeoffs\n\nGood fit for:\n- custom event analytics across several Val Town projects\n- product funnels and lightweight reporting\n- simple owner-controlled instrumentation\n\nNot designed for:\n- session replay\n- identity stitching across devices\n- advanced cohort analysis\n- enterprise-scale analytics workloads\n\n## Files\n\n- `main.ts`\n Full analytics service implementation\n- `README.md`\n Project documentation\n",[75],"pulls","branches","forks","envVars",{"_174":20,"_176":20},"connections",{"_174":20,"_175":20},"count","unfilledCount","emptyCount",{"_29":163,"_13":75,"_58":74,"_39":-5,"_31":32,"_156":78,"_157":148,"_33":183,"_35":36,"_61":49,"_159":165,"_63":24,"_161":-5,"_180":184,"_130":185},{"_29":155,"_13":60,"_58":59,"_39":-5,"_31":32,"_156":36,"_157":148,"_33":179,"_35":20,"_61":62,"_159":160,"_63":24,"_161":-5,"_180":181,"_130":182},["D",1773925905380],"children",[],[60],["D",1773928054187],[],[75],["D",1773925905345],{"_11":12,"_129":66},{"_11":12,"_125":-5,"_65":66,"_25":64,"_126":127,"_128":24},{"_35":78,"_13":16,"_29":32,"_117":83,"_118":-5,"_119":-5,"_120":-5,"_121":-5,"_122":-5,"_123":14,"_124":12},"ctx",{"_47":-5,"_150":223,"_224":225,"_226":227,"_228":24,"_229":24,"_230":24,"_231":148,"_232":-5,"_233":-7,"_234":-7,"_235":20,"_236":24,"_237":24,"_238":-5,"_239":24,"_240":24,"_241":24,"_242":-5},"ENV",{"_194":195,"_196":197,"_198":16,"_199":200,"_201":202,"_203":204,"_205":206,"_207":208,"_209":210,"_211":212,"_213":214,"_215":216,"_217":218,"_219":220,"_221":222},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

History