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:

# 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:

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:

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

Oder mit dem Deploy-Script:

./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

   <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:

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

Für Plausible.io (extern):

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
• Plausible Self-Hosting