# PV/UV analytics

## Recommended one-line install

Add this once in the shared application layout, replacing the site ID:

```html
<script defer src="https://doc.starhk.uk/sdk/analytics.js" data-site-id="site-xx"></script>
```

The SDK creates a first-party UUID v4 visitor ID in local storage, reports the initial page view, and tracks History API navigation for SPAs. It excludes common auth callback paths and deduplicates the same URL.

## Direct API contract

```http
POST https://auth.starhk.uk/analytics/collect
Content-Type: application/json

{
  "site_id": "site-xx",
  "event": "pageview",
  "path": "/pricing?source=home",
  "visitor_id": "<UUID-v4>",
  "referrer": "https://example.com/",
  "page_origin": "https://your-site.example"
}
```

Use `navigator.sendBeacon` when possible and `fetch(..., { keepalive: true })` as fallback. `page_origin` must equal the site's registered origin. Do not include email, user ID, prompts, tokens, or other personal data.

PV counts accepted page views. UV counts distinct visitor UUIDs for the reporting period. Star Admin displays daily/monthly totals and trends. Browser privacy controls, blocked storage, and offline navigation can reduce counts; analytics failure must never block the page.