Analytics con Umami

Cosa otterrai: un'unica istanza Umami che traccia tutte le tue app. In Coolify deployi Umami una volta; nella dashboard Umami aggiungi un "website" per app (Blog, Dashboard, ecc.); ogni app ha il suo NEXT_PUBLIC_UMAMI_WEBSITE_ID. Stesso URL dello script, ID diversi.

Deploy di Umami su Coolify

Coolify → il tuo progetto → Add Resource
Cerca Umami nei service template
Selezionalo e deploy. Coolify configura PostgreSQL, env var e SSL in automatico
Assegna un dominio (es. analytics.your-domain.com) nelle impostazioni della resource
Apri la dashboard Umami (es. https://analytics.your-domain.com), login admin / umami, cambia la password in Settings → Profile

Aggiungi il primo sito

Esempio: il tuo blog è your-domain.com. Vuoi tracciarlo.

Apri la dashboard Umami (es. https://analytics.your-domain.com)
Websites → Add website
Riempi:
- Name: Blog (o your-domain.com)
- Domain: your-domain.com (il dominio del sito che stai tracciando)
Salva
Click su Edit sul nuovo sito → copia il Website ID (UUID, es. a1b2c3d4-e5f6-7890-abcd-ef1234567890)

Quel UUID è il NEXT_PUBLIC_UMAMI_WEBSITE_ID per il blog.

Integrazione nel blog (Coolify)

Coolify → la tua applicazione blog → Configuration → Environment Variables
Aggiungi:
- NEXT_PUBLIC_UMAMI_SCRIPT_URL = https://analytics.your-domain.com/script.js (il tuo dominio Umami + /script.js, senza porta se dietro Traefik sul 443)
- NEXT_PUBLIC_UMAMI_WEBSITE_ID = l'UUID che hai copiato da Umami
Save e Redeploy il blog

Il blog ha già il componente <Analytics /> nel layout. Una volta impostate le env var e fatto il redeploy, le pageview compariranno in Umami sotto il sito "Blog".

Importante: le var NEXT_PUBLIC_* vengono inglobate nel bundle al build time. Se le aggiungi o le cambi dopo il deploy, devi fare Redeploy perché il cambiamento abbia effetto.

Integrazione in Next.js (riferimento componente)

Componente Analytics (components/analytics.tsx)

"use client";

import Script from "next/script";

const scriptUrl = process.env.NEXT_PUBLIC_UMAMI_SCRIPT_URL;
const websiteId = process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID;

export function Analytics() {
  if (!scriptUrl || !websiteId) {
    return null;
  }

  return (
    <Script
      src={scriptUrl}
      data-website-id={websiteId}
      strategy="afterInteractive"
    />
  );
}

Aggiungi al layout (app/layout.tsx)

import { Analytics } from "@/components/analytics";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  );
}

Variabili d'ambiente (Coolify → app blog → Environment)

Variabile	Valore esempio
`NEXT_PUBLIC_UMAMI_SCRIPT_URL`	`https://analytics.your-domain.com/script.js`
`NEXT_PUBLIC_UMAMI_WEBSITE_ID`	`a1b2c3d4-e5f6-7890-abcd-ef1234567890` (da Umami)

Redeploy. Le pageview compaiono in Umami in pochi minuti.

Più app, più siti

Una sola istanza Umami, tante app. Nella dashboard Umami, Websites → Add website per ogni app. Ogni sito ha un ID univoco.

App	Dominio	Sito Umami	WEBSITE_ID
Blog	your-domain.com	Blog	uuid-1
Mazza Immobiliare	mazzaimmobiliare.it	Mazza Immobiliare	uuid-2
Dashboard	app.your-domain.com	Dashboard	uuid-3

NEXT_PUBLIC_UMAMI_SCRIPT_URL è uguale per tutte le app (https://analytics.your-domain.com/script.js). NEXT_PUBLIC_UMAMI_WEBSITE_ID cambia per app. Crea un sito in Umami per ogni app, copia ogni ID nella env di quell'app. Copia il componente Analytics in ogni app Next.js; cambiano solo le env var.

Eventi custom (opzionale)

Per click, download o altre interazioni, usa umami.track().

Data attribute (niente JavaScript)

<button data-umami-event="Newsletter signup">Subscribe</button>
<a href="/file.pdf" data-umami-event="Download PDF">Download</a>

JavaScript

// Dopo che lo script Umami carica
if (typeof window !== "undefined" && window.umami) {
  window.umami.track("Button clicked", { name: "pricing" });
}

TypeScript: aggiungi a global.d.ts o a un file di tipi:

declare global {
  interface Window {
    umami?: {
      track: (
        eventNameOrPayload?: string | object | ((props: object) => object),
        eventData?: Record<string, string | number>
      ) => void;
    };
  }
}

Usa umami.track() (senza argomenti) per una pageview, umami.track("Event name") per gli eventi, oppure umami.track("Event", { key: "value" }) per eventi con dati.

Gli eventi compaiono in Umami sotto Websites → il tuo sito → Events.

Tracking delle pageview: umami.track() senza argomenti manda una pageview. Lo script di Umami 3 intercetta già history.pushState e history.replaceState, quindi la navigazione client-side in Next.js è tracciata in automatico. Non serve un route tracker manuale.

Troubleshooting

Nessuna visita in Umami?

URL dello script: usa https://analytics.your-domain.com/script.js senza :3000. La porta è interna; Traefik proxy sul 443.
Env var al build time: aggiungi le var in Coolify, poi Redeploy. I cambi a NEXT_PUBLIC_* richiedono una nuova build.
Ad blocker: testa in incognito senza estensioni. uBlock Origin blocca gli script di analytics.
Check rapido: apri il sito in incognito → DevTools → Network → filtra per send. Devi vedere richieste POST a analytics.your-domain.com/api/send con status 200. Se sì, il tracking funziona; i dati compaiono in Umami in 1-2 minuti.

Per una guida di troubleshooting più dettagliata (con header Cloudflare), vedi scripts/umami-troubleshooting.md in questa repo.

Cloudflare: geolocalizzazione (regione e città)

Se Umami sta dietro Cloudflare, di default riceve solo il paese. Per regione e città:

Cloudflare Dashboard → il tuo sito → Rules → Settings → Managed Transforms
Abilita Add visitor location headers
Assicurati che il dominio Umami (es. analytics.your-domain.com) sia Proxied (nuvoletta arancione) in DNS

Cloudflare aggiunge CF-IPCountry, CF-RegionCode e CF-IPCity alle richieste. Traefik di solito li inoltra. Se no, imposta SKIP_LOCATION_HEADERS=1 nella env di Umami per usare il suo geo database interno (meno preciso su regione/città).

Checklist

Umami deployato su Coolify
Dominio e SSL per la dashboard Umami
Password admin cambiata
Sito creato in Umami, ID copiato
NEXT_PUBLIC_UMAMI_SCRIPT_URL e NEXT_PUBLIC_UMAMI_WEBSITE_ID nelle env dell'app
Componente Analytics nel layout
App ridistribuita, pageview visibili in Umami