logo hsb.horse

Architecture Decision Record

Einführungsrichtlinie für Partytown und Google Analytics (GA4)

GA4 (G-WZ3RT34EZZ) über Partytown einführen, um Pageview-Messung zu starten und die Hauptthread-Last zu reduzieren.

Angenommen #analytics #ga4 #partytown #performance #privacy

Übersetzungen

Englisch Französisch Japanisch Portugiesisch Koreanisch

Einführungsrichtlinie für Partytown und Google Analytics (GA4)

Entscheidung

  • Für Zugriffsauswertung wird Google Analytics 4 (GA4) verwendet, mit der Measurement-ID G-WZ3RT34EZZ.
  • GA-Skripte werden mit @astrojs/partytown über type="text/partytown" in einen Web Worker ausgelagert.
  • Die Ausgabe der Tracking-Tags wird in einer gemeinsamen Ebene zentralisiert (dedizierte Komponente unter Layout).
  • Tracking wird nur auf Produktions-URLs aktiviert; lokal und in Preview-Umgebungen bleibt es deaktiviert.
  • Der initiale Umfang ist auf Pageview-Tracking begrenzt; Custom Events werden in einem separaten ADR definiert.
  • In der Erstversion werden keine zusätzlichen Privacy-Parameter in gtag('config', ...) überschrieben; der Produktionsbetrieb startet mit den GA4-Standardeinstellungen.

Implementierungskonventionen

PunktRegel
Skriptausführunggtag.js mit type="text/partytown" laden.
ID-VerwaltungMeasurement-ID nicht in Seiten hartkodieren; per PUBLIC_GA_MEASUREMENT_ID injizieren (Initialwert G-WZ3RT34EZZ).
AusgabebedingungTags nur ausgeben, wenn PROD aktiv ist und eine Measurement-ID vorhanden ist.
PlatzierungZentral im gemeinsamen Layout, nicht pro Seite individuell.
Event-UmfangInitial nur page_view; keine beliebigen Custom Events in dieser Phase.

Kontext

Aktuell ist keine Zugriffsanalyse aktiv, daher fehlen Daten zu Akquise, Seitenreichweite und Nutzungstrends. Gleichzeitig können Third-Party-Skripte auf dem Hauptthread TTI/FID/INP verschlechtern.

Das Projekt bündelt Head-Verantwortung bereits im gemeinsamen Astro-Layout; Analytik sollte diesem Muster folgen. Wegen der mehrsprachigen Struktur ist eine seitenweise Implementierung fehleranfälliger und soll vermieden werden.

Optionen

  • Option A: Standard-gtag.js direkt im Hauptthread laden
  • Option B: gtag.js über @astrojs/partytown im Worker ausführen (gewählt)
  • Option C: GA4 nicht einführen und auf ein anderes leichtgewichtiges Analytics-Tool wechseln

Begründung

  • Performance: Partytown verlagert Third-Party-Ausführung vom Hauptthread in den Worker.
  • Betriebssicherheit: Zentrale Ausgabe verhindert fehlende Tags bei neuen Seiten.
  • Schrittweise Einführung: Start mit Pageviews, Event-Design später in separatem ADR.
  • Nachvollziehbarkeit: Produktions-Gating und die Annahme „Start mit GA-Defaults“ sind explizit dokumentiert.

Konsequenzen

  • @astrojs/partytown muss als Abhängigkeit ergänzt und in astro.config.mjs integriert werden.
  • Eine gemeinsame Analytics-Komponente (oder gleichwertige Verantwortung) muss in Layout eingebunden werden.
  • Der Betrieb von PUBLIC_GA_MEASUREMENT_ID muss definiert und gepflegt werden.
  • Die Datenschutzerklärung muss um GA4-Nutzung und Messzweck ergänzt werden.
  • Akzeptanzkriterien:
    • GA-Tags werden nur in Produktion ausgegeben
    • Pageviews sind auf allen öffentlichen Seiten messbar
    • Hauptthread-Regression bleibt in Lighthouse (oder gleichwertig) im akzeptablen Bereich