# Installing the Eurolytics tracking script
Eurolytics is privacy-first, cookie-free web analytics. One small script (~2 KB gzipped), no cookies, no consent banner needed for the tracking itself, GDPR-compliant by design.
This guide is written to be readable by both humans and AI assistants. A machine-readable version is at https://eurolytics.app/docs/install.json.
## Quick start
1. Sign up / log in at https://eurolytics.app and add your site — you get a **site ID** (a UUID).
2. Paste this snippet into the `` of every page, replacing `SITE_ID` with your site ID:
```html
```
3. Visit your site in a normal browser tab. Your visit appears on the dashboard within a minute or two.
The exact snippet (with your site ID filled in) is shown in the dashboard under **your site → Settings → Tracking**. It can also be fetched programmatically: `GET /api/v1/sites/{siteId}/snippet` with an API key, or the `get_tracking_snippet` tool on the MCP server at https://eurolytics.app/api/mcp.
Important: use only this one `` snippet. Do not add the script more than once per page.
## Fully automated setup (AI agents / MCP)
An AI coding agent (Claude, ChatGPT, or any MCP-capable client) can add a site and confirm tracking works without a human touching the dashboard.
**Connect to the MCP server** at https://eurolytics.app/api/mcp, one of two ways:
1. **OAuth** (recommended) — add the URL as a connector. The client is redirected to sign in (or sign up) in the browser; no account has to exist beforehand and no key needs to be copied anywhere.
2. **In-chat signup** (for headless environments with no browser) — call the separate, unauthenticated onboarding server at https://eurolytics.app/api/mcp/onboarding: `start_signup { email, name }` emails a 6-digit code, then `complete_signup { email, code }` returns an account API key. Reconnect to https://eurolytics.app/api/mcp with `Authorization: Bearer `.
**Agent workflow** once connected:
1. `create_site { domain }` — registers the site and returns the tracking snippet.
2. Paste the snippet into the site's `` — the agent edits the codebase directly, following the framework-specific instructions below.
3. `verify_installation { site_id }` — fetches the live homepage and checks for events; returns a status (`verified`, `snippet_found_awaiting_traffic`, `wrong_site_id`, `not_installed`, or `site_unreachable`) plus guidance on what to do next.
## What is tracked automatically
- **Pageviews**, including single-page-app navigations (`pushState`/`replaceState`/`popstate` and back/forward-cache restores) — no extra SPA setup needed.
- **Engagement**: visibility-aware time on page and maximum scroll depth.
- **Outbound link clicks** and **file downloads** (both can be turned off).
- **404 pages** (heuristic, based on document title/body classes).
- UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`).
Bot and automated traffic is classified at ingestion and excluded from your stats.
## Framework-specific installation
### Plain HTML
Paste the snippet inside the tag of every page (or of your shared template).
```html
...
```
### Next.js (App Router)
Add the script to the root layout (app/layout.tsx) using next/script so it loads once for the whole app. Client-side navigations are tracked automatically.
```tsx
import Script from 'next/script';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
### Next.js (Pages Router)
Add the script in pages/_app.tsx (or pages/_document.tsx) using next/script.
```tsx
import Script from 'next/script';
import type { AppProps } from 'next/app';
export default function App({ Component, pageProps }: AppProps) {
return (
<>
);
}
```
### Nuxt 3
Register the script globally in nuxt.config.ts under app.head.script.
```ts
export default defineNuxtConfig({
app: {
head: {
script: [
{
src: 'https://events.eurolytics.app/js/script.js?s=SITE_ID',
defer: true,
'data-site-id': 'SITE_ID',
},
],
},
},
});
```
### SvelteKit
Paste the snippet into src/app.html, just before %sveltekit.head%.
```html
...
%sveltekit.head%
```
### Astro
Add the snippet to the of your shared layout component. Use is:inline so Astro does not bundle or transform it.
```astro
...
```
### React / Vue / other Vite SPA
Paste the snippet into the of index.html at the project root. SPA route changes are tracked automatically.
```html
...
```
### WordPress
Use a header-scripts plugin (e.g. WPCode: Code Snippets → Header & Footer → Header) and paste the snippet, or add it before in your child theme's header.php.
```html
```
### Shopify
In the admin go to Online Store → Themes → Edit code, open layout/theme.liquid, and paste the snippet just before .
```html
```
### Webflow
Go to Site settings → Custom code → Head code, paste the snippet, save, and publish the site. Requires a plan that allows custom code.
```html
```
### Google Tag Manager
Create a Custom HTML tag with the snippet and fire it on the All Pages trigger. A direct install is preferred (fewer blockers, earlier load), but GTM works.
```html
```
## Configuration options
Two ways to configure, in order of precedence:
1. **Dashboard toggles** (recommended): your site → Settings → Tracking. Because the snippet loads the script with `?s=SITE_ID`, the dashboard settings are injected at load time — changes apply without touching your site's code, and they override any data-attributes.
2. **Data-attributes** on the script tag, e.g. `