Documentation

Tally is a self-hosted, privacy-first web analytics engine. This documentation covers installation, configuration, the tracking script, the REST API, and production deployment.

How it works

Tally has three components:

1. Tracker (~3KB) — A JavaScript snippet you add to your site. It sends pageview events, scroll depth, focus time, and SPA navigation to your Tally server via sendBeacon .
2. Server — A Bun-based HTTP server that receives events, enriches them with GeoIP and user-agent data, and writes to SQLite. Also serves the dashboard and API.
3. Dashboard — A server-rendered analytics dashboard with overview metrics, page analytics, traffic sources, geo/device breakdowns, realtime visitors, and CSV export.

Key concepts

• Sessions — Visitors are identified by a client-generated UUID stored in a first-party cookie ( tally_sid ). The server never sets cookies. Sessions last 30 days.
• Events — The tracker sends four event types: pageview , scroll , exit , and ping .
• Sites — Tally supports multiple sites via site_id . Each site has its own token for origin validation.
• Enrichment — The server enriches sessions with GeoIP (country, region, city), user-agent (browser, OS, device type), referrer classification, and UTM extraction.
• Rollups — Daily aggregation runs on an interval, pre-computing stats for faster dashboard queries.

What's tracked

• Page views and unique visitors
• Scroll depth (percentage)
• Focus time (milliseconds the page was visible)
• Referrer and UTM parameters
• Country, region, city (via GeoIP)
• Browser, OS, device type (via user-agent)
• SPA navigation (pushState, replaceState, popstate, hashchange)

What's NOT tracked

• No cookies beyond a first-party session ID
• No fingerprinting
• No personal data collection
• No cross-site tracking
• No data sent to third parties