Intlayer Analytics Dokumentation

@intlayer/analytics ist ein optionales Begleitpaket, das Ihnen mitteilt, welche Inhalte Ihren Besuchern tatsächlich angezeigt werden — welche Seite, in welchem Gebietsschema (Locale) und welcher spezifische Teil des übersetzten Inhalts — damit Sie Ihr Publikum verstehen und A/B-Tests für Inhalte durchführen können.

Inhaltsverzeichnis

Was es nachverfolgt

@intlayer/analytics bündelt drei Arten von anonymen Ereignissen:

Ereignisse werden im Speicher gesammelt und als einzelne Batch-Anfrage etwa alle 20 Sekunden gesendet — niemals bei jedem Tastendruck oder Rendern — sodass die Analytik niemals die erste Renderzeit beeinträchtigt oder eine Anfrage pro Interaktion hinzufügt.

Wie es A/B-Tests für Inhalte ermöglicht

Mit Intlayer können Sie bereits inhaltliche Varianten deklarieren (z. B. ein hero-banner Wörterbuch mit einer control und einer black_friday Variante). @intlayer/analytics schließt den Kreis:

1. getVariant(experimentKey, variants) weist jede anonyme Sitzung deterministisch einer Variante zu — eine reine Funktion der Sitzungs-ID und des Experimentschlüssels, sodass die Zuweisung über die gesamte Sitzung hinweg stabil ist und keine Server-Roundtrips vor dem ersten Rendern erfordert (kein Flackern, keine Layout-Verschiebung).
2. Jedes content_exposure Ereignis enthält die variant, die angezeigt wurde.
3. Mit useConversion() können Sie dieser Variante ein Ziel (z. B. "cta_click") zuschreiben.
4. Der Endpunkt für die Experimentergebnisse des Dashboards vergleicht die Konversionsraten pro Variante, einschließlich der statistischen Signifikanz (ein z-Test).

Installation

@intlayer/analytics ist eine optionale Peer-Abhängigkeit — sie wird niemals automatisch durch ein Framework-Paket installiert. Fügen Sie es neben intlayer hinzu:

npm install @intlayer/analytics

Wenn Sie es nicht installieren, wird jeder Integrationspunkt in ein No-Op aufgelöst — siehe Keine Kosten, wenn nicht installiert unten.

Konfiguration

Analytics verwendet den vorhandenen editor Konfigurationsblock wieder — es gibt kein separates analytics Konfigurationsschema auszufüllen:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // Wird auch als Analytics-Ingestion-Endpunkt verwendet
    clientId: "your-client-id", // Wird auch als Analytics-Projektschlüssel verwendet
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — die Basis-URL, an die Analytics-Ereignisse gesendet werden (POST {backendURL}/api/analytics/events).
• editor.clientId — der öffentliche Projektschlüssel, der jedem aufgenommenen Ereignis zugeschrieben wird. Es fungiert auch als Aktivierungsschalter: Analytics bleibt vollständig deaktiviert (und als Dead-Code eliminiert, siehe unten), bis clientId konfiguriert ist.

Wenn Sie Intlayer selbst hosten, verweist die Analytik automatisch auf Ihre eigene Instanz, da sie editor.backendURL teilt.

Framework-Unterstützung

Analytics ist mit dem freigegebenen IntlayerProvider von react-intlayer verdrahtet und steht daher heute überall dort zur Verfügung, wo dieser Provider verwendet wird:

Verwendung

Automatische Nachverfolgung auf Provider-Ebene

Es sind keine Codeänderungen erforderlich. Sobald @intlayer/analytics installiert und editor.clientId konfiguriert ist, führt der IntlayerProvider automatisch Folgendes aus:

• initialisiert den Analytics-Client beim Mounten,
• zeichnet einen page_view beim ersten Laden auf,
• zeichnet einen page_view bei jedem Gebietsschema-Wechsel auf,
• startet die ca. 20-sekündige Flush-Schleife und flusht verbleibende Ereignisse beim Unmounten / Schließen des Tabs (über navigator.sendBeacon, andernfalls fetch(..., { keepalive: true })).

Automatische Nachverfolgung auf Node-Ebene

Jedes Mal, wenn useIntlayer einen Inhalt zur Anzeige auflöst, meldet der Interpreter ein content_exposure Ereignis für genau diese dictionaryKey + Schlüsselpfad + Gebietsschema — auch hier sind keine Codeänderungen erforderlich. Wiederholte Expositionen desselben Knotens innerhalb eines Flush-Fensters werden zu einem einzigen Ereignis mit einem count zusammengefasst, sodass eine Liste, die 50 Mal neu gerendert wird, nicht 50 Ereignisse sendet.

Nachverfolgung von Konversionen für A/B-Tests

Verwenden Sie useConversion(), um einer Variante, die eine Sitzung gesehen hat, ein Ziel zuzuschreiben:

Auflösung einer Variante auf der Clientseite

Datenschutz & Leistung

• Anonym durch Design: Sitzungen werden durch eine rotierende ID identifiziert; das Backend speichert nur einen SHA-256-Hash dieser ID — niemals die rohe ID, niemals eine IP-Adresse.
• Standort ist grob: nur ein Ländercode, der aus CDN-Geolokalisierungs-Headern (cf-ipcountry, x-vercel-ip-country, ...) abgeleitet wird — es wird keine IP gelesen oder gespeichert.
• URLs schließen Suchparameter aus: standardmäßig werden Query-Strings nie erfasst.
• Sampling: sampleRate ermöglicht es Ihnen, bei Traffic-starken Apps nur einen Bruchteil der Content-Exposure-Ereignisse zu behalten.
• Gepoolt: eine Anfrage ungefähr alle 20 Sekunden (flushInterval), oder früher, wenn der Puffer voll ist (maxBufferSize) — niemals eine Anfrage pro Ereignis.

Keine Kosten, wenn nicht installiert

@intlayer/analytics folgt genau dem gleichen optionalen Abhängigkeitsmuster wie @intlayer/editor:

• Jeder Integrationspunkt lädt das Paket über einen dynamischen import() umhüllt in try/catch — eine App, die @intlayer/analytics nie installiert, zahlt weder für Bundle-Größe noch Laufzeitkosten und sieht nie einen Fehler;
• eine Umgebungsvariable zur Kompilierzeit (INTLAYER_ANALYTICS_ENABLED), die von @intlayer/config automatisch auf 'false' gesetzt wird, wenn editor.clientId nicht konfiguriert ist, ermöglicht es Bundlern, die gesamte Integration als Dead-Code zu eliminieren;
• Analytics ist im Intlayer Editor/CMS-Vorschau-Iframe deaktiviert, sodass Editor-Sitzungen niemals als echter Traffic gewertet werden.

Dashboard: Analytics-Seite

Sobald Ihr Projekt Ereignisse gesammelt hat, zeigt die Seite Analytics im Intlayer Dashboard (sichtbar in der Seitenleiste, sobald ein Projekt ausgewählt ist) Folgendes an:

• Aktive Nutzer — eindeutige Besucher über das ausgewählte rollierende Zeitfenster (7 / 30 / 90 Tage).
• Nutzer heute und Nutzer in den letzten 7 Tagen.
• Seitenaufrufe über das ausgewählte Zeitfenster.
• Ein Verlaufsdiagramm der täglichen eindeutigen Besucher.
• Registerkarten für die Aufschlüsselung nach Gebietsschemas (Locales) und Standort, die Ihre Zielgruppe nach Gebietsschema und Land einordnen.

Backend-API-Referenz

Alle Lese-Endpunkte erfordern Authentifizierung; die Ingestion ist öffentlich und wird durch clientId zugeordnet.

Sie können diese auch programmgesteuert mit dem CMS SDK aufrufen:

import { createIntlayerCMS } from "@intlayer/api";import { analyticsEndpoint } from "@intlayer/api/analytics";const cms = createIntlayerCMS();const { data: audience } = await analyticsEndpoint(cms).getAudience(30);

Nützliche Links

• Dynamische Wörterbücher - Kollektionen & Varianten
• Intlayer CMS - CMS SDK
• Intlayer Visueller Editor
• Konfigurationsreferenz
• Self-Hosting-Leitfaden