hoerdle/docs/PLAUSIBLE_SETUP.md

# Plausible Analytics Konfiguration

## Übersicht

Die App verwendet Plausible Analytics für anonyme Nutzungsstatistiken. Die Konfiguration erfolgt über Umgebungsvariablen.

## Konfiguration

### Erforderliche Variablen

**Nur eine Variable ist erforderlich:**

1. **`NEXT_PUBLIC_PLAUSIBLE_SCRIPT_SRC`** (erforderlich)
   - Die vollständige URL zum Plausible-Script
   - Beispiel (selbst gehostet): `https://plausible.elpatron.me/js/script.js`
   - Beispiel (extern): `https://plausible.io/js/script.js`

**Hinweis:** Die Domain wird automatisch aus der Request-Domain erkannt. Beide Domains (`hoerdle.de` und `hördle.de`) werden automatisch getrackt.

### Konfiguration für Docker

Da es sich um **Build-Time Variablen** handelt (NEXT_PUBLIC_*), muss die App neu gebaut werden, wenn diese geändert werden.

#### Schritt 1: Umgebungsvariablen setzen

Erstelle oder bearbeite eine `.env`-Datei im Projektverzeichnis:

```bash
# Plausible Analytics (Script-URL ist erforderlich)
NEXT_PUBLIC_PLAUSIBLE_SCRIPT_SRC=https://plausible.elpatron.me/js/script.js

# Die Domain wird automatisch erkannt - keine weitere Konfiguration nötig!
```

#### Schritt 2: docker-compose.yml konfigurieren

Stelle sicher, dass die Variablen als Build-Args übergeben werden:

```yaml
services:
  hoerdle:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        NEXT_PUBLIC_PLAUSIBLE_SCRIPT_SRC: ${NEXT_PUBLIC_PLAUSIBLE_SCRIPT_SRC}
```

Die `docker-compose.example.yml` enthält bereits diese Konfiguration.

#### Schritt 3: App neu bauen

**WICHTIG:** Nach Änderung der Plausible-Variablen muss die App neu gebaut werden:

```bash
docker compose build --no-cache
docker compose up -d
```

Oder mit dem Deploy-Script:

```bash
./scripts/deploy.sh
```

### Konfiguration für beide Domains

Die App unterstützt **automatisches Tracking** für beide Domains (`hoerdle.de` und `hördle.de`). Die Domain wird automatisch aus dem Request-Header ausgelesen und entsprechend in Plausible getrackt.

#### Automatisches Domain-Tracking

**Standard-Verhalten:** Die App erkennt automatisch, welche Domain aufgerufen wurde, und setzt die entsprechende `data-domain` im Plausible-Script:
- `https://hoerdle.de/*` → `data-domain="hoerdle.de"`
- `https://hördle.de/*` → `data-domain="hördle.de"`

#### In Plausible konfigurieren

Du hast zwei Optionen:

##### Option 1: Beide Domains als separate Sites (separate Statistiken) - Empfohlen für getrenntes Tracking

1. Erstelle in Plausible zwei separate Sites:
   - `hoerdle.de`
   - `hördle.de`

2. Fertig! Die App trackt automatisch die richtige Domain.

**Vorteil:** Separate Statistiken für jede Domain.

##### Option 2: Beide Domains als Aliase für eine Site (gemeinsame Statistiken)

1. Erstelle in Plausible eine Site: `hoerdle.de`
2. Füge `hördle.de` als Alias hinzu (in den Site-Einstellungen)

3. Fertig! Die App trackt automatisch die richtige Domain, und Plausible behandelt beide als Aliase für die gleiche Site.

**Hinweis:** Du musst nichts zusätzlich konfigurieren. Die App trackt automatisch `hoerdle.de` oder `hördle.de` basierend auf der Request-Domain, und Plausible erkennt beide als Aliase.

**Vorteil:** Gemeinsame Statistiken für beide Domains in einer Site.

#### Empfehlung

Für separate Statistiken: **Option 1** (automatisches Tracking)
Für gemeinsame Statistiken: **Option 2** (Aliase in Plausible)

### Automatische CSP-Anpassung

Die Content Security Policy (CSP) in `proxy.ts` wird automatisch an die konfigurierte Plausible-URL angepasst. Die Domain wird automatisch aus der Script-URL extrahiert.

### Prüfen der Konfiguration

Nach dem Neubau kannst du prüfen, ob Plausible korrekt geladen wird:

1. **Browser-Entwicklertools öffnen**
   - Network-Tab: Suche nach dem Plausible-Script
   - Console: Prüfe auf Fehler

2. **Prüfe die Meta-Tags**
   ```html
   <script defer data-domain="hoerdle.de" src="https://plausible.elpatron.me/js/script.js"></script>
   ```

3. **Prüfe Plausible-Dashboard**
   - Öffne dein Plausible-Dashboard
   - Prüfe, ob Daten ankommen

### Troubleshooting

#### Plausible wird nicht geladen

- Prüfe, ob die Umgebungsvariablen korrekt gesetzt sind
- Prüfe, ob die App neu gebaut wurde (Build-Time Variablen!)
- Prüfe Browser-Console auf CSP-Fehler

#### CSP blockiert Plausible

Die CSP sollte automatisch angepasst werden. Falls Probleme auftreten:
- Prüfe, ob `NEXT_PUBLIC_PLAUSIBLE_SCRIPT_SRC` korrekt gesetzt ist
- Prüfe die Logs des Containers

#### Daten werden nicht in Plausible angezeigt

- Prüfe, ob die Domain in Plausible als Site konfiguriert ist
- Prüfe, ob `data-domain` Attribut mit der konfigurierten Domain übereinstimmt
- Prüfe Browser-Console auf Fehler beim Laden des Scripts

### Beispiel-Konfiguration

#### Für selbst gehostetes Plausible:

```bash
NEXT_PUBLIC_PLAUSIBLE_SCRIPT_SRC=https://plausible.elpatron.me/js/script.js
```

#### Für Plausible.io (extern):

```bash
NEXT_PUBLIC_PLAUSIBLE_SCRIPT_SRC=https://plausible.io/js/script.js
```

**Hinweis:** Die Domain wird automatisch aus der Request-Domain erkannt - keine weitere Konfiguration nötig!

### Weitere Informationen

- [Plausible Dokumentation](https://plausible.io/docs)
- [Plausible Self-Hosting](https://plausible.io/docs/self-hosting)