# Nanolytica Cloud

> Privacy-first analytics for websites, mobile apps, smart TVs, and IoT devices.

Nanolytica Cloud is a multi-tenant analytics platform powered by ClickHouse. No cookies, no personal data, no tracking scripts phoning home to third parties. GDPR and CCPA compliant by design.

## Features

- Web tracking via a single script tag, native app tracking via HTTP API
- Real-time dashboards with WebSocket live updates
- Behavioral insights: journey analysis, conversion funnels, retention cohorts, session explorer
- Custom events via `window.Nanolytica.track(name, props, { value })`
- Goals (pageview-path or event-name) with completions, conversion rate, and revenue in the site currency
- Auto-tracking opt-ins for outbound link clicks, file downloads, and 404 pages
- Core Web Vitals (LCP, INP, CLS, FCP, TTFB) with per-page breakdown
- Advanced filter operators (eq, neq, contains, not-contains, starts-with, regex) across all 11 dimensions; AND/OR match modes
- UTM campaign tracking with all 5 standard parameters
- Dimension filtering by browser, OS, device, country, referrer, screen size
- Combined views across multiple sites
- Bot and crawler detection (55+ patterns)
- CSV export (includes goal completions section)
- Public shareable dashboards

## Tracking

### Web

Add to any page:

```html
<script defer src="https://cloud.nanolytica.org/nanolytica.js" data-site-id="YOUR-SITE-UUID"></script>
```

### Native Apps (Mobile, TV, IoT)

POST to `/api/collect`:

```json
{
  "site_id": "YOUR-SITE-UUID",
  "path": "/home",
  "referrer": "",
  "user_agent": "MyApp/1.2.3 (iOS 17; iPhone)",
  "screen_size": "390x844",
  "duration_sec": 0,
  "scroll_depth": 0,
  "utm_source": "",
  "utm_medium": "",
  "utm_campaign": "",
  "utm_content": "",
  "utm_term": ""
}
```

Fields: `site_id` (required, UUID), `path` (max 2048), `referrer` (max 2048), `user_agent` (max 512), `screen_size` (WIDTHxHEIGHT), `duration_sec` (0-86400), `scroll_depth` (0-100), `utm_*` (max 256 each). For custom events also include `event_name` (≤ 64 chars, `^[a-zA-Z0-9_-]+$`), optional `props` (object, ≤ 10 keys), and optional `value` (number, for revenue goals).

Response: 204 No Content (accepted), 400 Bad Request (validation error), 429 Too Many Requests (rate limited).

## Privacy

- No cookies, no localStorage, no fingerprinting
- IP addresses hashed with per-site daily rotating salt, never stored raw
- Do Not Track (DNT: 1) respected, event discarded entirely
- Data retention: 365-day TTL in ClickHouse
- Compliant with GDPR, CCPA, ePrivacy, PECR

## UTM Campaign Tracking

All 5 standard UTM parameters captured automatically from URL query strings: utm_source, utm_medium, utm_campaign, utm_content, utm_term. Also supports `ref` and `source` as aliases for utm_source. Session-level attribution (first pageview only). utm_source merges with organic referrer (UTM takes priority).

## Behavioral Insights

- **Journey**: top page-to-page transitions, entry pages, exit pages
- **Funnels**: multi-step conversion paths with drop-off tracking (ClickHouse windowFunnel)
- **Retention**: cohort grid by first-visit week/month with color-coded return rates
- **Sessions**: individual visitor sessions with page-by-page timelines
- **Performance**: Core Web Vitals (LCP, INP, CLS, FCP, TTFB) scored with Google thresholds, per-page breakdown
- **Goals**: pageview-path or event-name conversion goals with completions, unique visitors, conversion rate, and revenue total in the site's display currency

## Custom Events & Goals

Fire arbitrary events from the tracking snippet:

```js
Nanolytica.track('cta_click');
Nanolytica.track('signup', { plan: 'pro', source: 'pricing-page' });
Nanolytica.track('purchase', { plan: 'pro' }, { value: 49.99 });
```

Event name: max 64 chars, matches `^[a-zA-Z0-9_-]+$`. Props: up to 10 key/value pairs (keys ≤ 64 chars, values ≤ 256 chars). Optional numeric `value` sums into revenue. Names starting with `nanolytica_` are reserved for auto-tracking.

### Auto-tracking (opt-in)

Add `data-*` attributes to the snippet, or toggle per site under Setup → Auto-tracking:

```html
<script defer src="https://cloud.nanolytica.org/nanolytica.js" data-site-id="YOUR-UUID"
    data-track-outbound data-track-downloads data-track-404></script>
```

- `data-track-outbound` — fires `nanolytica_outbound` on clicks to different hosts (props: url, host)
- `data-track-downloads` — fires `nanolytica_file_download` on pdf/zip/csv/docx/xlsx/mp3/mp4/… (props: url, ext). Downloads win over outbound to avoid double counts.
- `data-track-404` — fires `nanolytica_404` when the page contains `<meta name="nanolytica-404" content="1">` (props: path, referrer)

### Goals

Two kinds:

- **Pageview** — path match with operators `eq`, `starts_with`, `contains`, `regex`.
- **Event** — event-name match with optional prop filters (`eq`, `neq`, `contains`).

Goals show completions, unique visitors, conversion rate (against the period-filtered unique-visitor denominator), and revenue total in the site's currency (default USD; USD/EUR/GBP/JPY/CAD/AUD/TRY/INR/BRL/CHF supported). Goals respect the dashboard period selector, timezone, and active filters, and render read-only on public dashboards.

## Stack

- Go / Echo — HTTP server, auth, middleware
- ClickHouse — analytics storage (MergeTree, partitioned by month)
- SQLite — user accounts, sites, funnels, goals, per-site currency and auto-tracking flags
- templ — type-safe HTML templates
- Tailwind CSS — styling
- TypeScript — tracking script and dashboard frontend

## Links

- Website: https://cloud.nanolytica.org
- Documentation: https://cloud.nanolytica.org/documents
- Self-hosted (open source): https://github.com/eringen/nanolytica
- Issues: https://github.com/eringen/nanolytica/issues