Analytics

First-Party-Webanalyse — PostHog, Google Analytics, Plausible, Mixpanel, Segment und weitere — als Adapter in blume.config.ts.

Blume bindet Analytics für dich über eine analytics-Liste in blume.config.ts ein. Jeder Eintrag ist ein Adapter, den du aus blume/analytics importierst: einer pro Anbieter, plus script() für alles, wofür es keinen gibt.

import { defineConfig } from "blume";
import { googleAnalytics, plausible, posthog, vercel } from "blume/analytics";

export default defineConfig({
  analytics: [
    posthog({ key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }),
    vercel(),
    googleAnalytics({ id: "G-XXXXXXXXXX" }),
    plausible({ domain: "docs.example.com" }),
  ],
});

Adapter werden in der Reihenfolge, in der du sie auflistest, in den <head> ausgegeben, und du kannst beliebig viele kombinieren. Jeder Adapter besteht aus reinen Daten: Was er zurückgibt, wird zusammen mit dem Rest deiner Konfiguration validiert und direkt in die gebaute Website eingebettet. Er kann also jeden JSON-Wert enthalten, aber niemals eine Funktion. Eine durchgereichte Option, die sich nicht als JSON darstellen lässt (eine Funktion, undefined, ein Bigint), lässt die Validierung mit Angabe ihres Pfads fehlschlagen, statt aus dem Build zu verschwinden.

Analytics wird nur in Produktions-Builds geladen. Die Skripte werden von blume build ausgegeben, niemals von blume dev, sodass lokaler Traffic nie in deinen Dashboards landet und du kein separates „Entwicklungs“-Projekt brauchst.

Wenn du deine Leser vorher um Zustimmung bitten willst, setze consent: Jeder Adapter auf dieser Seite wartet dann, bis der Leser Analytics erlaubt.

Jede der folgenden Kennungen — ein Projektschlüssel, eine Mess-ID, ein Site-Token — ist die öffentliche, browserseitige Kennung aus dem Installations-Snippet des jeweiligen Anbieters. Jeder Adapter rendert genau dieses Snippet, du kannst sie also gefahrlos in dein Docs-Repository committen; Blume fragt nie nach einem Geheimnis.

Adapter

Blume-Dokumentationen verwenden einen clientseitigen Router, daher tauscht die meiste Navigation nur Inhalte innerhalb der Seite aus, statt die Seite vollständig neu zu laden. Jeder Adapter zählt diese Navigationen als Seitenaufrufe: Anbieter, deren Skript Änderungen am Verlauf selbstständig verfolgt, brauchen nichts weiter, und für diejenigen, die nur echte Seitenladevorgänge zählen (PostHog, Segment, Hightouch), sendet Blume den Seitenaufruf selbst. Die zwei Ausnahmen sind die Tag-Manager — Google Tag Manager und Adobe laden einen Container, dessen eigene Regeln entscheiden, was ausgelöst wird. Gib ihm also einen Trigger für Verlaufsänderungen.

PostHog

Übergib deinen Projekt-API-Schlüssel an posthog(), um PostHog hinzuzufügen. Der Host ist standardmäßig PostHog Cloud US; setze host für EU Cloud (https://eu.i.posthog.com) oder eine selbst gehostete Instanz.

analytics: [
  posthog({
    key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    host: "https://us.i.posthog.com", // optional, this is the default
  }),
],

key und host sind die beiden Optionen, die Blume selbst abbildet (host wird zu api_host). Alles andere, was du übergibst — persistence, capture_pageview, autocapture, disable_session_recording und jede andere posthog.init-Option —, wird unverändert an posthog.init weitergereicht.

Blume sendet für jede Navigation des Client-Routers nur dann einen $pageview, solange PostHog ausschließlich Seitenladevorgänge erfasst — so verhält sich PostHog, wenn du weder capture_pageview noch defaults setzt. Mit capture_pageview: "history_change" oder einem defaults-Datum wie "2025-05-24" aus dem aktuellen Snippet von PostHog erfasst PostHog Navigationen selbst, sodass Blume nichts zusätzlich sendet. Mit capture_pageview: false werden überhaupt keine Seitenaufrufe gesendet.

Vercel Web Analytics

Füge vercel() hinzu, um Vercel Web Analytics einzubinden. Blume rendert die offizielle Astro-Komponente von Vercel. Sie bindet das First-Party-Skript ein, das von deiner eigenen Domain ausgeliefert wird, sobald Web Analytics für das Projekt im Vercel-Dashboard aktiviert ist.

analytics: [vercel()],

Es werden keine Schlüssel benötigt — das Skript meldet an das Projekt, unter dem es deployt ist. Daten werden nur bei Vercel-Deployments erfasst, wo der Endpunkt /_vercel/insights existiert. Jede Option, die du übergibst, wird als Prop an die Komponente weitergereicht (mode, debug, endpoint, scriptSrc, …). beforeSend ist eine Funktion und kann nicht über die Konfiguration übergeben werden, weise window.webAnalyticsBeforeSend also stattdessen in einem script()-Adapter zu.

Cloudflare Web Analytics

Für Cloudflare Web Analytics gibt es zwei Einrichtungsvarianten, und nur eine davon braucht einen Adapter.

Proxy-Zone (automatische Einrichtung). Wenn Cloudflare deine Website ausliefert — ein Worker mit eigener Domain, Pages oder eine beliebige Zone mit aktivierter orangefarbener Wolke —, aktiviere Web Analytics für die Zone im Cloudflare-Dashboard, und das war’s. Cloudflare bindet den Beacon am Edge ein, also lass cloudflare() weg; würdest du es zusätzlich auflisten, würde jeder Seitenaufruf doppelt gezählt.

Jeder andere Host (manuelle Einrichtung). Für eine Website, die Cloudflare nicht per Proxy ausliefert, füge die Website im Dashboard unter Web Analytics hinzu, kopiere den Token aus dem JS-Snippet, das du dort erhältst (den token innerhalb von data-cf-beacon), und übergib ihn hier. Blume rendert dasselbe Beacon-Tag wie das Snippet.

analytics: [
  cloudflare({
    token: "0123456789abcdef0123456789abcdef",
  }),
],

Das gesamte Optionsobjekt wird zum data-cf-beacon-JSON des Beacons, sodass jede weitere Beacon-Einstellung (spa, …) direkt durchgereicht wird.

Google Analytics 4

Übergib die Mess-ID deines GA4-Web-Datenstreams (G-…, in den Details des Streams unter Admin → Data Streams der Property) an googleAnalytics(). Blume rendert das Google-Tag genau so, wie es die Installationsanleitung des Streams vorgibt: den asynchronen gtag.js-Loader plus den dataLayer-Bootstrap und den config-Aufruf.

analytics: [
  googleAnalytics({
    id: "G-XXXXXXXXXX",
    anonymize_ip: true, // optional: any other `config` parameter
  }),
],

id ist die einzige Option, die Blume selbst abbildet. Alles andere, was du übergibst, wird unverändert beim gtag('config', …)-Aufruf mitgegeben (send_page_view, cookie_domain, debug_mode, …). Die erweiterten Analysen von GA4 zählen Verlaufsänderungen standardmäßig als Seitenaufrufe, sodass clientseitige Navigationen ohne zusätzliche Einrichtung erfasst werden. Google Analytics braucht ein bis zwei Tage, bis neue Daten erscheinen; die Erweiterung Google Analytics Debugger zeigt Anfragen in Echtzeit an.

Google Tag Manager

Übergib deine Container-ID (GTM-…, wird im Header des Arbeitsbereichs angezeigt) an googleTagManager(). Blume rendert den <head>-Teil des Container-Snippets; das <noscript>-iframe ist für Browser ohne JavaScript gedacht, die ohnehin nie Analytics ausführen.

analytics: [
  googleTagManager({
    id: "GTM-XXXXXXX",
    dataLayer: "dataLayer", // optional, this is the default
  }),
],

Welche Tags wodurch ausgelöst werden, legt die Konfiguration des Containers fest. Clientseitige Navigationen erreichen den Container als Verlaufsänderungen, also löse Pageview-Tags über einen History Change-Trigger aus statt über den Trigger für das Laden der Seite. Cookie-Consent-Banner richtest du ebenfalls selbst im Container ein.

Plausible

Übergib die Domain, die du in Plausible hinzugefügt hast, an plausible(). Für eine selbst gehostete Instanz oder eine hinter einem Proxy setzt du host auf deren Origin; standardmäßig wird Plausible Cloud verwendet.

analytics: [
  plausible({
    domain: "docs.example.com",
    host: "https://plausible.example.com", // optional, defaults to https://plausible.io
  }),
],

domain wird zu data-domain, und host bestimmt, von wo /js/script.js geladen wird. Jede weitere Option wird zu einem eigenen data--Attribut am Tag (api: "/api/event" → data-api). Skriptvarianten, deren Zusatzverhalten im Dateinamen steckt (script.outbound-links.js, …), sind ein anderes Tag; lade sie mit script().

Clics

Übergib die Projekt-ID aus Configure → Tracking im Clics-Dashboard an clics(). Blume bindet den Browser-Tracker von Clics mit dem erforderlichen data-project-id-Attribut ein.

import { clics } from "blume/analytics";

analytics: [clics({ projectId: "YOUR_PROJECT_ID" })],

Der Tracker zählt Seitenladevorgänge und clientseitige Navigationen automatisch, einschließlich der Navigationen des Client-Routers von Blume. Füge also keinen zweiten Pageview-Hook hinzu. Außerdem verfolgt er standardmäßig ausgehende Links. Setze disableOutboundLinks: true, um diese Events abzuschalten. Für einen Produktions-Build, den du auf localhost als Vorschau ansiehst, setze allowLocalhost: true; ein gewöhnliches blume dev lädt keine Analytics.

Die eigenen Events von Blume erreichen Clics nicht: Sein Browser-Tracker hat keine globale Event-Funktion, an die sie weitergeleitet werden könnten. Um eigene Events zu senden, rufe den track()-Helper aus @clicsdev/tracker in deinem eigenen Client-Code auf.

Fathom

Übergib deine Site-ID (aus den Skripteinstellungen der Website in Fathom) an fathom().

analytics: [
  fathom({
    site: "ABCDEFGH",
    "honor-dnt": "true", // optional: any other `data-` setting
  }),
],

site wird zu data-site. Jede weitere Option wird zu einem eigenen data--Attribut am Tag (honor-dnt, excluded-domains, canonical, …), jeweils als String. spa ist standardmäßig "auto", damit Fathom die Navigationen des Client-Routers zählt; übergib einen eigenen spa-Wert, um das zu überschreiben.

Pirsch

Übergib deinen Identifikationscode (Settings → Developer → Identification Code in Pirsch) an pirsch().

analytics: [
  pirsch({
    code: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  }),
],

code wird zu data-code, und Blume gibt dem Tag die ID pianjs, anhand derer das Skript von Pirsch sich selbst findet. Jede weitere Option wird zu einem eigenen data--Attribut (dev, exclude, include, domain, endpoint, …).

Databuddy

Übergib deine Client-ID (aus den Einstellungen der Website in Databuddy) an databuddy().

analytics: [
  databuddy({
    clientId: "xxxxxxxxxxxxxxxxxxxxx",
    "track-web-vitals": "true", // optional: any other `data-` setting
    "skip-patterns": '["/admin/*"]',
  }),
],

clientId wird zu data-client-id. Jede weitere Option wird zu einem eigenen data--Attribut am Tag. Benenne sie also so, wie das Attribut heißt, in kebab-case (track-web-vitals, track-errors, track-outgoing-links, api-url, …). Einen camelCase-Namen wie trackWebVitals ignoriert Databuddy. Werte sind Strings: "true" oder "false" für einen Schalter und ein JSON-Array für skip-patterns und mask-patterns. Jeden anderen Listenwert liest Databuddy als leer.

OneDollarStats

Füge die Domain der Website in OneDollarStats hinzu und liste dann oneDollarStats() auf. Ein Schlüssel wird nicht benötigt, weil OneDollarStats Events anhand der Domain, von der sie kommen, einer Website zuordnet.

analytics: [oneDollarStats()],

Jede Option wird zu einem eigenen data--Attribut am Tag, und Werte sind Strings:

• hostname meldet jedes Event unter diesem Hostnamen (docs.example.com, ohne https:// oder Pfad), und zwar auf jedem Host, nicht nur auf localhost. So zählen auch Preview-Deployments und Staging als Traffic dieser Website. Lass die Option weg, es sei denn, jeder Build soll unter diesem Namen melden.
• devmode: "true" zusammen mit hostname erlaubt einem lokalen blume preview, Events zu senden. Auf localhost sendet der Tracker ohne beides nichts, lass beides also aus der committeten Konfiguration heraus.
• url ist der Collector-Endpunkt, an den Events gesendet werden (standardmäßig https://collector.onedollarstats.com/events), nicht die URL der Website.
• autocollect: "false" schaltet automatische Seitenaufrufe ab.
• "hash-routing": "true" sendet bei jeder Navigation einen Seitenaufruf, selbst wenn sich nur das #fragment ändert, etwa bei einem Klick im Inhaltsverzeichnis. Bei "false" lässt Blume das Attribut weg, weil der Tracker Hash-Routing aktiviert, sobald es vorhanden ist.

Mixpanel

Übergib deinen Projekt-Token (Projekteinstellungen → Access Keys in Mixpanel) an mixpanel(). Wenn das Projekt Datenresidenz in der EU oder in Indien nutzt, setze region entsprechend, sonst verwirft Mixpanel die Events.

analytics: [
  mixpanel({
    token: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    region: "eu", // optional: "us" (default), "eu", or "in"
  }),
],

token und region sind die Optionen, die Blume selbst abbildet (region wird zu api_host). Außerdem setzt Blume track_pageview auf "url-with-path-and-query-string", sodass die Bibliothek jede Navigation selbst erfasst. Alles andere, was du übergibst — einschließlich track_pageview —, wird unverändert an mixpanel.init weitergereicht (persistence, autocapture, record_sessions_percent, …).

Amplitude

Übergib deinen Projekt-API-Schlüssel (Projekteinstellungen in Amplitude) an amplitude(). Blume rendert das Script-Loader-Snippet des Browser SDK: das mit deinem Schlüssel versehene SDK-Bundle plus den init-Aufruf.

analytics: [
  amplitude({
    key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    serverZone: "EU", // optional: any other `init` option
  }),
],

key ist die einzige Option, die Blume selbst abbildet. Die init-Optionen gehen von dem aus, was das Dashboard-Snippet mitbringt — autocapture: true und fetchRemoteConfig: true —, und alles andere, was du übergibst, wird unverändert darübergelegt. Autocapture deckt Seitenaufrufe und Verlaufsänderungen ab, sodass clientseitige Navigationen gezählt werden.

Segment

Übergib den Write Key deiner JavaScript-Quelle in Segment an segment(). Wenn du analytics.js über eine eigene Domain auslieferst, um Werbeblocker zu umgehen, setze cdn auf diesen Origin.

analytics: [
  segment({
    key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    cdn: "https://cdn.example.com", // optional, defaults to https://cdn.segment.com
  }),
],

key und cdn sind die Optionen, die Blume selbst abbildet: Das Snippet lädt die Bibliothek von cdn und weist sie an, auch ihre Integrationen von dort abzurufen. Alles andere, was du übergibst, wird unverändert als analytics.load-Optionen weitergereicht (integrations, …).

Hightouch

Übergib den Write Key deiner Event-Quelle in Hightouch an hightouch(). Der Host der Events-API liegt standardmäßig in der Region US East; setze host (ohne Schema), wenn dein Workspace eine andere nutzt.

analytics: [
  hightouch({
    key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    host: "us-east-1.hightouch-events.com", // optional, this is the default
  }),
],

key und host sind die Optionen, die Blume selbst abbildet (host wird zu apiHost). Alles andere, was du übergibst, wird unverändert als htevents.load-Optionen weitergereicht.

Heap

Übergib deine App-ID (die Umgebungs-ID in den Installationseinstellungen des Projekts in Heap) an heap().

analytics: [
  heap({
    id: "1234567890",
    disableTextCapture: true, // optional: any other `heap.load` option
  }),
],

id ist die einzige Option, die Blume selbst abbildet. Alles andere, was du übergibst, wird unverändert zum Konfigurationsobjekt von heap.load.

Hotjar

Übergib deine Site-ID (die Zahl im Tracking-Code der Website in Hotjar) an hotjar().

analytics: [
  hotjar({
    id: 1234567,
    version: 6, // optional, this is the default
  }),
],

id entspricht hjid und version entspricht hjsv im Tracking-Code von Hotjar; weitere Optionen nimmt der Adapter nicht an.

Microsoft Clarity

Übergib deine Projekt-ID (aus dem Tracking-Code des Projekts in Clarity) an clarity().

analytics: [
  clarity({
    id: "xxxxxxxxxx",
  }),
],

Weitere Optionen nimmt der Adapter nicht an; die Einstellungen von Clarity verwaltest du in dessen Dashboard.

LogRocket

Übergib deine App-ID (org/app, aus den Projekteinstellungen in LogRocket) an logrocket(). Blume rendert das Installations-Snippet: das SDK plus den abgesicherten LogRocket.init-Aufruf.

analytics: [
  logrocket({
    id: "your-org/your-app",
    release: "1.2.0", // optional: any other `init` option
  }),
],

id ist die einzige Option, die Blume selbst abbildet. Alles andere, was du übergibst, wird unverändert an LogRocket.init weitergereicht (release, console, network, dom, …). Ein Sanitizer für Requests oder Responses ist eine Funktion und kann nicht über die Konfiguration übergeben werden; lass in diesem Fall den Adapter weg und rufe LogRocket.init selbst in einem script()-Adapter auf.

Clearbit

Übergib deinen öffentlichen API-Schlüssel (pk_…) an clearbit(). Blume rendert das Clearbit-Tag, das alle Tags lädt, die du in Clearbit verwaltest — etwa Reveal oder Formulare.

analytics: [
  clearbit({
    key: "pk_xxxxxxxxxxxxxxxx",
  }),
],

Weitere Optionen nimmt der Adapter nicht an.

Adobe Analytics

Übergib die Embed-Skript-URL deiner Launch-Umgebung (Adobe Experience Platform Tags) an adobe(). Kopiere sie aus der Installationsanleitung der Umgebung unter Environments in Data Collection; die URL der Produktionsumgebung sieht so aus: https://assets.adobedtm.com/…/launch-….min.js.

analytics: [
  adobe({
    url: "https://assets.adobedtm.com/xxxxxxxx/launch-xxxxxxxx.min.js",
  }),
],

Blume lädt das Skript asynchron; was es erfasst, bestimmen die Regeln der Property. Clientseitige Navigationen laden die Seite nicht neu, also gib der Property eine Regel für Verlaufsänderungen (oder rufe _satellite.track in einem script()-Adapter auf).

Eigene Skripte

Verwende script(), um einen beliebigen Anbieter ohne Adapter zu laden oder das Tag eines Anbieters in einer Form, die sein Adapter nicht rendert. Jeder Aufruf rendert ein <script>-Tag und muss genau eines von src (extern) oder content (inline) setzen.

analytics: [
  // Umami
  script({
    src: "https://cloud.umami.is/script.js",
    strategy: "defer",
    attributes: { "data-website-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" },
  }),
  // An inline snippet
  script({
    content: "console.log('analytics ready')",
  }),
],

attributes ist eine Zuordnung zusätzlicher HTML-Attribute (data-*, id, …), die auf das Tag verteilt werden, und strategy fügt externen Skripten async oder defer hinzu.

Ein wurzelrelativer src-Wert verweist auf eine Datei in public/ (src: "/js/redirects.js" für public/js/redirects.js). Unter einer deployment.base wird ihm deshalb wie einem Link die Base vorangestellt: Mit base: "/docs" lädt das Tag /docs/js/redirects.js. Ein src-Wert, der bereits mit der Base beginnt, bleibt so, wie er geschrieben ist, und eine absolute oder protokollrelative URL wird unverändert durchgereicht. Für ein Skript, das außerhalb der Base der Website ausgeliefert wird, gibst du also seine vollständige URL an.

Optionen

Eigene Events

Das Seiten-Feedback von Blume (feedback sowie feedback_comment, wenn schriftliches Feedback aktiviert ist), die Suche (search, search_select), der Assistent (ask, ask_answer, ask_error) und der Player der Vorlesefunktion (narration_play, narration_complete) senden eigene Events über jeden konfigurierten Adapter, der eine Client-API hat — PostHog, Mixpanel, Heap, Segment, Hightouch, Amplitude, LogRocket, Adobe, Google Analytics, Google Tag Manager (als { event }-Push auf window.dataLayer), Plausible, Databuddy, Fathom, OneDollarStats (mit jedem Eigenschaftswert als String), Pirsch, Clarity, Hotjar und Vercel. Fathom, Clarity und Hotjar nehmen nur den Namen eines Events entgegen und zählen daher jedes Event ohne seine Eigenschaften. Cloudflare und Clearbit haben keine Event-API, und Clics hat keine globale, die Blume aufrufen könnte. Jedes Event wird außerdem als blume:track-CustomEvent auf window ausgelöst, mit { event, props } in detail, sodass ein script()-Adapter es an jedes beliebige andere Ziel weiterleiten kann. Der Assistent sendet den Text einer Frage nie an einen Anbieter, und die Suche sendet ihre Suchanfragen so, wie sie eingegeben wurden, es sei denn, du setzt search.analytics.queries auf false – dann wird stattdessen die Länge jeder Suchanfrage gesendet. In beiden Fällen erreicht der Text weiterhin das blume:track-Event, damit ein Listener, den du selbst schreibst, ihn weiterleiten kann. Zum Deployen deiner gebauten Website siehe Deployment.