DotCMS SDK Analytics Installationsanleitung

Dieser Skill bietet Schritt-für-Schritt-Anleitungen zur Installation und Konfiguration des @dotcms/analytics SDK im Next.js-Beispielprojekt unter /core/examples/nextjs.

Überblick

Das @dotcms/analytics SDK ist die offizielle JavaScript-Bibliothek von dotCMS zur Verfolgung von inhaltsbezogenen Ereignissen und Analysen. Es bietet:

Automatische Seitenaufrufverfolgung
Conversion-Tracking (Käufe, Downloads, Anmeldungen usw.)
Benutzerdefiniertes Event-Tracking
Sitzungsverwaltung (30-Minuten-Timeout)
Anonyme Benutzeridentitätsverfolgung
UTM-Kampagnenparameterverfolgung
Event-Batching/Queuing für die Leistung

🚨 Wichtig: Verständnis der Analytics-Komponenten

KRITISCH: useContentAnalytics() erfordert IMMER die Konfiguration als Parameter. Der Hook verwendet KEIN React Context.

Rollen der Komponenten

<DotContentAnalytics /> - Automatischer Seitenaufruf-Tracker
- Einziger Zweck: Automatisches Verfolgen von Seitenaufrufen bei Routenänderungen
- KEIN React Context Provider
- Stellt KEINE Konfiguration für untergeordnete Komponenten bereit
- Platziere im Root-Layout für automatische Seitenaufrufverfolgung
useContentAnalytics(config) - Manueller Tracking-Hook
- Wird für benutzerdefiniertes Event-Tracking verwendet
- Erfordert IMMER den config-Parameter
- Importiere die zentrale Konfiguration in jeder Komponente, die sie verwendet

Korrektes Nutzungsmuster

// 1. Zentrale Konfigurationsdatei erstellen (einmal)
// /src/config/analytics.config.js
export const analyticsConfig = {
  siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
  server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
  autoPageView: true,
  debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
};

// 2. DotContentAnalytics zum Layout für automatische Seitenaufrufverfolgung hinzufügen (optional)
// /src/app/layout.js
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

<DotContentAnalytics config={analyticsConfig} />;

// 3. Konfiguration in jeder Komponente importieren, die den Hook verwendet
// /src/components/MyComponent.js
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

const { track } = useContentAnalytics(analyticsConfig); // ✅ Konfiguration erforderlich!

Warum die Konfiguration zentralisieren? Obwohl du sie in jeder Komponente importieren musst, verhindert die Zentralisierung Duplikate und erleichtert Aktualisierungen.

Kurze Einrichtungszusammenfassung

Hier ist der vollständige Einrichtungsablauf:

1. Paket installieren
   └─> npm install @dotcms/analytics

2. Zentrale Konfigurationsdatei erstellen
   └─> /src/config/analytics.config.js
       └─> export const analyticsConfig = { siteAuth, server, debug, ... }

3. (Optional) DotContentAnalytics für automatische Seitenaufrufverfolgung hinzufügen
   └─> /src/app/layout.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> <DotContentAnalytics config={analyticsConfig} />

4. Konfiguration in JEDER Komponente importieren, die den Hook verwendet
   └─> /src/components/MyComponent.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> const { track } = useContentAnalytics(analyticsConfig) // ✅ Konfiguration erforderlich!

Wichtige Vorteile der zentralisierten Konfiguration:

✅ Einheitliche Quelle der Wahrheit für Konfigurationswerte
✅ Einfaches Aktualisieren von Umgebungsvariablen an einem Ort
✅ Konsistente Konfiguration über alle Komponenten hinweg
✅ Besser als das Duplizieren der Konfiguration in jeder Datei

Installationsschritte

1. Das Paket installieren

Navigiere zum Next.js-Beispielverzeichnis und installiere das Paket:

cd /core/examples/nextjs
npm install @dotcms/analytics

2. Installation überprüfen

Überprüfe, ob das Paket zu package.json hinzugefügt wurde:

grep "@dotcms/analytics" package.json

Erwartete Ausgabe: "@dotcms/analytics": "latest" oder eine ähnliche Version.

3. Zentrale Analytics-Konfiguration erstellen

Erstelle eine dedizierte Konfigurationsdatei, um deine Analytics-Einstellungen zu zentralisieren. Dies erleichtert die Wartung und Wiederverwendung in deiner gesamten Anwendung.

Datei: /core/examples/nextjs/src/config/analytics.config.js

/**
 * Zentrale Analytics-Konfiguration für dotCMS Content Analytics
 *
 * Diese Konfiguration wird verwendet von:
 * - DotContentAnalytics Provider in layout.js
 * - useContentAnalytics() Hook bei eigenständiger Verwendung (optional)
 *
 * Erforderliche Umgebungsvariablen:
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG (optional)
 */
export const analyticsConfig = {
  siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
  server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
  autoPageView: true, // Automatische Seitenaufrufverfolgung bei Routenänderungen
  debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
  queue: {
    eventBatchSize: 15, // Senden, wenn 15 Ereignisse in der Warteschlange sind
    flushInterval: 5000, // Oder alle 5 Sekunden senden (ms)
  },
};

Vorteile dieses Ansatzes:

✅ Einheitliche Quelle der Wahrheit für die Analytics-Konfiguration
✅ Einfach zu importieren und in Komponenten wiederzuverwenden
✅ Zentrale Verwaltung von Umgebungsvariablen
✅ Typsicher und IDE-Autovervollständigung freundlich
✅ Einfach zu testen und in Unit-Tests zu mocken

4. Analytics im Next.js-Layout konfigurieren

Aktualisiere die Root-Layout-Datei, um den Analytics-Provider mit der zentralen Konfiguration einzubinden.

Datei: /core/examples/nextjs/src/app/layout.js

import { Inter } from "next/font/google";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
}

Aktualisiert mit Analytics (unter Verwendung der zentralen Konfiguration):

import { Inter } from "next/font/google";
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <DotContentAnalytics config={analyticsConfig} />
        {children}
      </body>
    </html>
  );
}

4. Umgebungsvariablen hinzufügen

Erstelle oder aktualisiere die .env.local-Datei im Stammverzeichnis des Next.js-Projekts:

Datei: /core/examples/nextjs/.env.local

# dotCMS Analytics Konfiguration
NEXT_PUBLIC_DOTCMS_SITE_AUTH=your_site_auth_key_here
NEXT_PUBLIC_DOTCMS_SERVER=https://your-dotcms-server.com

Wichtig: Ersetze your_site_auth_key_here durch deinen tatsächlichen dotCMS Analytics Site-Authentifizierungsschlüssel. Diesen erhältst du aus der Analytics-App in deiner dotCMS-Instanz.

5. `.env.local` zu `.gitignore` hinzufügen

Stelle sicher, dass die Umgebungsdatei nicht in die Versionsverwaltung übertragen wird:

# Prüfen, ob bereits ignoriert
grep ".env.local" /core/examples/nextjs/.gitignore

# Falls nicht vorhanden, hinzufügen
echo ".env.local" >> /core/examples/nextjs/.gitignore

Verwendungsbeispiele

Grundeinrichtung (Automatische Seitenaufrufe)

Mit der obigen Konfiguration werden Seitenaufrufe bei jeder Routenänderung automatisch verfolgt. Kein zusätzlicher Code erforderlich!

Manueller Seitenaufruf mit benutzerdefinierten Daten

Verfolge Seitenaufrufe mit zusätzlichem Kontext:

"use client";

import { useEffect } from "react";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function MyComponent() {
  // ✅ IMMER Konfiguration übergeben - aus zentraler Konfigurationsdatei importieren
  const { pageView } = useContentAnalytics(analyticsConfig);

  useEffect(() => {
    // Seitenaufruf mit benutzerdefinierten Daten verfolgen
    pageView({
      contentType: "blog",
      category: "technology",
      author: "john-doe",
      wordCount: 1500,
    });
  }, []);

  return <div>Inhalt hier</div>;
}

Benutzerdefinierte Ereignisse verfolgen

Verfolge spezifische Benutzerinteraktionen:

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function CallToActionButton() {
  // ✅ IMMER Konfiguration übergeben - aus zentraler Konfigurationsdatei importieren
  const { track } = useContentAnalytics(analyticsConfig);

  const handleClick = () => {
    // Benutzerdefiniertes Ereignis verfolgen
    track("cta-click", {
      button: "Jetzt kaufen",
      location: "hero-section",
      price: 299.99,
    });
  };

  return <button onClick={handleClick}>Jetzt kaufen</button>;
}

Formularübermittlungs-Tracking

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function ContactForm() {
  const { track } = useContentAnalytics(analyticsConfig);

  const handleSubmit = async (e) => {
    e.preventDefault();

    // Formularübermittlung verfolgen
    track("form-submit", {
      formName: "contact-form",
      formType: "lead-gen",
      source: "homepage",
    });

    // Formular absenden...
  };

  return <form onSubmit={handleSubmit}>{/* Formularfelder */}</form>;
}

Video-/Medieninteraktions-Tracking

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function VideoPlayer({ videoId }) {
  const { track } = useContentAnalytics(analyticsConfig);

  const handlePlay = () => {
    track("video-play", {
      videoId,
      duration: 120,
      autoplay: false,
    });
  };

  const handleComplete = () => {
    track("video-complete", {
      videoId,
      watchPercentage: 100,
    });
  };

  return (
    <video onPlay={handlePlay} onEnded={handleComplete}>
      {/* Videoquellen */}
    </video>
  );
}

E-Commerce-Produktansichts-Tracking

"use client";

import { useEffect } from "react";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function ProductPage({ product }) {
  const { track } = useContentAnalytics(analyticsConfig);

  useEffect(() => {
    // Produktansicht verfolgen
    track("product-view", {
      productId: product.sku,
      productName: product.title,
      category: product.category,
      price: product.price,
      inStock: product.inventory > 0,
    });
  }, [product]);

  return <div>{/* Produktdetails */}</div>;
}

Conversion-Tracking (E-Commerce-Kauf)

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function CheckoutButton({ product, quantity }) {
  const { conversion } = useContentAnalytics(analyticsConfig);

  const handlePurchase = () => {
    // Checkout-Logik hier ausführen...
    // Nach erfolgreicher Zahlungsbestätigung:

    // Conversion NUR nach erfolgreichem Kauf verfolgen
    conversion("purchase", {
      value: product.price * quantity,
      currency: "USD",
      productId: product.sku,
      productName: product.title,
      quantity: quantity,
      category: product.category,
    });
  };

  return <button onClick={handlePurchase}>Kauf abschließen</button>;
}

Conversion-Tracking (Lead-Generierung)

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function DownloadWhitepaper() {
  const { conversion } = useContentAnalytics(analyticsConfig);

  const handleDownload = () => {
    // Download-Logik hier ausführen...
    // Nach erfolgreichem Download:

    // Conversion NUR nach erfolgreichem Download verfolgen
    conversion("download", {
      fileType: "pdf",
      fileName: "whitepaper-2024.pdf",
      category: "lead-magnet",
    });
  };

  return (
    <button id="download-btn" onClick={handleDownload}>
      Whitepaper herunterladen
    </button>
  );
}

Konfigurationsoptionen

Analytics-Konfigurationsobjekt

Option	Typ	Erforderlich	Standard	Beschreibung
`siteAuth`	`string`	Ja	-	Site-Authentifizierungsschlüssel von dotCMS Analytics
`server`	`string`	Ja	-	Ihre dotCMS-Server-URL
`debug`	`boolean`	Nein	`false`	Ausführliche Protokollierung für Debugging-Zwecke aktivieren
`autoPageView`	`boolean`	Nein	`true` (React)	Seitenaufrufe bei Routenänderungen automatisch verfolgen
`queue`	`QueueConfig \| false`	Nein	Standard-Queue-Einstellungen	Event-Batching-Konfiguration
`impressions`	`ImpressionConfig \| boolean`	Nein	`false`	Inhalts-Impression-Tracking (standardmäßig deaktiviert)
`clicks`	`boolean`	Nein	`false`	Klick-Tracking mit 300ms Drosselung (standardmäßig deaktiviert)

Queue-Konfiguration

Steuert, wie Ereignisse gebündelt und gesendet werden:

Option	Typ	Standard	Beschreibung
`eventBatchSize`	`number`	`15`	Max. Ereignisse pro Stapel - automatisch senden, wenn erreicht
`flushInterval`	`number`	`5000`	Zeit in ms zwischen den Übertragungen

Queuing deaktivieren (sofort senden):

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  queue: false, // Ereignisse sofort senden
};

Impression-Tracking-Konfiguration

Steuert die automatische Verfolgung der Sichtbarkeit von Inhalten:

Option	Typ	Standard	Beschreibung
`intersectionThreshold`	`number`	`0.5`	Anteil des Elements, der sichtbar sein muss, um als Impression zu gelten (0,0 bis 1,0)
`observerDelay`	`number`	`1000`	Verzögerung in ms, bevor ein Element nach dem Rendern als Impression erfasst wird
`observerRootMargin`	`string`	`"0px"`	Margin um das Viewport für die Intersection-Erkennung (CSS-ähnliche Syntax)

Beispiel mit benutzerdefinierten Impression-Einstellungen:

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  impressions: {
    intersectionThreshold: 0.75, // 75% des Elements müssen sichtbar sein
    observerDelay: 2000, // 2 Sekunden warten, bevor eine Impression aufgezeichnet wird
    observerRootMargin: "50px", // 50px um das Viewport erweitern
  },
};

Fehlerbehebung

Häufige Probleme

Problem	Lösung
Ereignisse werden nicht aufgezeichnet	Überprüfen, ob `siteAuth` und `server` korrekt in `.env.local` gesetzt sind
`useContentAnalytics` gibt `undefined` zurück	Stelle sicher, dass die Konfiguration als Parameter übergeben wird
`DotContentAnalytics` verfolgt keine Seitenaufrufe	Überprüfen, ob die Konfiguration korrekt an die Komponente übergeben wird
Debugging-Meldungen werden nicht angezeigt	Setze `NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG=true` in `.env.local`
Ereignisse werden nicht sofort gesendet	Passe die Queue-Konfiguration an oder setze `queue: false` für sofortiges Senden
CORS-Fehler in der Konsole	Stelle sicher, dass der dotCMS-Server CORS für die Domain der Anwendung erlaubt

Nächste Schritte

Entdeckungs-APIs erkunden - Erfahre, wie du Inhalte mit den dotCMS Entdeckungs-APIs abrufen kannst, die Analytics und Personalisierung unterstützen
Personalisierung implementieren - Nutze die erfassten Analytics-Daten, um personalisierte Inhalte bereitzustellen
Benutzerdefinierte Dashboards erstellen - Visualisiere deine Analytics-Daten mit benutzerdefinierten Dashboards

In Ihrer bevorzugten KI fragen

Dokumentation