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 Abhängigkeit jedes Framework-Pakets (react-intlayer, next-intlayer, vue-intlayer, …) und ist daher in den meisten Projekten bereits vorhanden. Installieren Sie es explizit, wenn Ihr Setup optionale Abhängigkeiten überspringt (npm install --no-optional, …):

npm install @intlayer/analytics

Die Installation des Pakets genügt, um Analytics einzuschalten: analytics.enabled ist standardmäßig true, und @intlayer/config setzt es auf false, sobald das Paket in Ihrem Projekt nicht gefunden wird. Wenn Sie es nicht installieren, wird jeder Integrationspunkt in ein No-Op aufgelöst — siehe Keine Kosten, wenn nicht installiert unten.

Konfiguration

Analytics benötigt keine Konfiguration, um zu starten: Es ist standardmäßig aktiviert und verwendet den bestehenden editor-Konfigurationsblock für Endpunkt und Projektschlüssel.

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.

Deaktivieren (Opt-out)

Der optionale analytics-Block steuert die Erfassung — oder schaltet sie ab:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  analytics: {
    enabled: false, // Standard: true — nimmt die gesamte Integration aus dem Bundle
    flushInterval: 20_000, // Millisekunden zwischen zwei gebündelten Übertragungen
    sampleRate: 1, // Anteil der aufgezeichneten Sitzungen, von 0 (keine) bis 1 (alle)
  },
};

export default config;

Das Deinstallieren von @intlayer/analytics hat dieselbe Wirkung wie enabled: false. Die vollständige Feldliste finden Sie in der Konfigurationsreferenz.

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

</Tab> </Tabs>

Gewichtungen sind optional — geben Sie eine pro Variante an, um die Aufteilung zu beeinflussen, z. B. useExperiment("homepage-hero", ["default", "black_friday"], [9, 1]).

Das untergeordnete Element liest dann die Variant des Wörterbuchs, die übereinstimmt:

import { useIntlayer } from "react-intlayer";

export const HeroBanner = ({ variant }: { variant: string }) => {
  const { headline, cta } = useIntlayer("hero-banner", { variant });

  return (
    <section>
      <h1>{headline}</h1>
      <a>{cta}</a>
    </section>
  );
};

Das Lesen der Variante in einer untergeordneten Komponente ist das, was dies außerhalb von React funktioniert: In Vue, Svelte, Solid und Angular wird der Selektor, der an useIntlayer übergeben wird, erfasst, wenn die Komponente initialisiert wird, daher muss das Lesen in einer Komponente stattfinden, die nur einmal bereitgestellt wird, wenn die Variante bekannt ist.

Wenn das Experiment eine ganze Seite abdeckt und nicht nur ein einzelnes Dictionary, verschieben Sie die Variante stattdessen auf den Provider — siehe Ambient variant. Jedes useIntlayer darunter wird dann dagegen aufgelöst, ohne dass Änderungen an der Aufrufstelle erforderlich sind.

Wenn du die Raw Assignment außerhalb einer Komponente benötigst, greife direkt auf den Client zu:

getVariant weist nur zu — es zeichnet die Exposition nicht auf. Verwenden Sie lieber useExperiment(), andernfalls hat die Konversionsrate keinen Nenner.

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 Compile-Zeit-Umgebungsvariable (INTLAYER_ANALYTICS_ENABLED), die von @intlayer/config automatisch auf 'false' gesetzt wird, wenn das Paket nicht installiert ist, analytics.enabled false ist oder editor.clientId nicht konfiguriert ist, ermöglicht Bundlern die Dead-Code-Elimination der gesamten Integration;
• 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);

Nur Server-seitig. createIntlayerCMS() authentifiziert sich mit clientId + clientSecret, und das Secret ist niemals im Browser verfügbar — dieser Code-Schnipsel würde unauthentifizierte Anfragen ausstellen, wenn er dort ausgeführt würde. Halten Sie ihn in einem Route Handler, Server Action oder Script.

Nützliche Links

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