Next.js Integration

Integriere usertrax in deine Next.js Anwendung, um Conversions und Benutzerinteraktionen zu verfolgen.

Setup in Next.js

Script Tag im Head hinzufügen

Füge das usertrax Script Tag in deinen HTML Head Bereich ein:

Für Pages Router - Aktualisiere pages/_document.js:

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="de">
      <Head>
        <script
          src="https://usertrax.io/cvs.js"
          data-key={process.env.NEXT_PUBLIC_USERTRAX_KEY}
          async
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Für App Router - Aktualisiere app/layout.js:

export default function RootLayout({ children }) {
  return (
    <html lang="de">
      <head>
        <script
          src="https://usertrax.io/cvs.js"
          data-key={process.env.NEXT_PUBLIC_USERTRAX_KEY}
          async
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Helper Funktionen erstellen

Erstelle eine neue Datei lib/usertrax.js in deinem Projekt:

// Helper Funktionen für häufige Events
export const trackConversion = (data) => {
  if (window.usertrax) {
    window.usertrax.push(data);
  } else {
    console.warn("Usertrax noch nicht geladen");
  }
};

export const trackPageView = (page) => {
  if (window.usertrax) {
    window.usertrax.push({
      event: "page_view",
      page: page,
    });
  } else {
    console.warn("Usertrax noch nicht geladen");
  }
};

export const trackEvent = (eventName, data = {}) => {
  if (window.usertrax) {
    window.usertrax.push({
      event: eventName,
      ...data,
    });
  } else {
    console.warn("Usertrax noch nicht geladen");
  }
};

Umgebungsvariablen hinzufügen
Erstelle oder aktualisiere deine .env.local Datei:
```
NEXT_PUBLIC_USERTRAX_KEY=dein_public_key_hier
```

Page View Tracking einrichten

Für Pages Router - Aktualisiere pages/_app.js:

// pages/_app.js (Pages Router)
import { useEffect } from "react";
import { useRouter } from "next/router";
import { trackPageView } from "../lib/usertrax";

function MyApp({ Component, pageProps }) {
  const router = useRouter();

  useEffect(() => {
    // Page Views verfolgen
    const handleRouteChange = (url) => {
      trackPageView(url);
    };

    router.events.on("routeChangeComplete", handleRouteChange);

    return () => {
      router.events.off("routeChangeComplete", handleRouteChange);
    };
  }, [router]);

  return <Component {...pageProps} />;
}

export default MyApp;

Für App Router - Erstelle app/components/PageTracker.jsx:

"use client";

import { useEffect } from "react";
import { usePathname } from "next/navigation";
import { trackPageView } from "../../lib/usertrax";

export default function PageTracker() {
  const pathname = usePathname();

  useEffect(() => {
    // Page Views verfolgen
    trackPageView(pathname);
  }, [pathname]);

  return null;
}

Dann füge es zu deinem app/layout.js hinzu:

import PageTracker from "./components/PageTracker";

export default function RootLayout({ children }) {
  return (
    <html lang="de">
      <head>
        <script
          src="https://usertrax.io/cvs.js"
          data-key={process.env.NEXT_PUBLIC_USERTRAX_KEY}
          async
        />
      </head>
      <body>
        <PageTracker />
        {children}
      </body>
    </html>
  );
}

Custom Hook erstellen

Erstelle einen Custom Hook für einfacheres Tracking in Komponenten:

import { useCallback } from "react";
import { trackConversion, trackEvent } from "../lib/usertrax";

export const useUsertrax = () => {
  const trackConversionEvent = useCallback((data) => {
    trackConversion(data);
  }, []);

  const trackCustomEvent = useCallback((eventName, data = {}) => {
    trackEvent(eventName, data);
  }, []);

  const trackFormSubmission = useCallback((formData) => {
    trackEvent("form_submitted", formData);
  }, []);

  const trackButtonClick = useCallback((buttonData) => {
    trackEvent("button_clicked", buttonData);
  }, []);

  return {
    trackConversion: trackConversionEvent,
    trackEvent: trackCustomEvent,
    trackFormSubmission,
    trackButtonClick,
  };
};

Verwendungsbeispiele

Conversion Tracking

import { useUsertrax } from "../hooks/useUsertrax";

export default function CheckoutForm() {
  const { trackConversion } = useUsertrax();

  const handlePurchase = async (orderData) => {
    try {
      // Kauf verarbeiten
      const response = await fetch("/api/checkout", {
        method: "POST",
        body: JSON.stringify(orderData),
      });

      if (response.ok) {
        // Conversion verfolgen
        trackConversion({
          event: "purchase",
          id: orderData.orderId,
          total: orderData.total,
          currency: "EUR",
          user_data: {
            email: orderData.email,
            firstname: orderData.firstName,
            lastname: orderData.lastName,
          },
          metadata: {
            products: orderData.items,
            payment_method: orderData.paymentMethod,
          },
        });
      }
    } catch (error) {
      console.error("Checkout Fehler:", error);
    }
  };

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

Formular Submissions verfolgen

import { useUsertrax } from "../hooks/useUsertrax";

export default function ContactForm() {
  const { trackFormSubmission } = useUsertrax();

  const handleSubmit = async (formData) => {
    try {
      // Formular absenden
      const response = await fetch("/api/contact", {
        method: "POST",
        body: JSON.stringify(formData),
      });

      if (response.ok) {
        // Formular Submission verfolgen
        trackFormSubmission({
          form_type: "contact",
          form_data: {
            name: formData.name,
            email: formData.email,
            message_length: formData.message.length,
          },
        });
      }
    } catch (error) {
      console.error("Formular Submission Fehler:", error);
    }
  };

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

Button Klicks verfolgen

import { useUsertrax } from "../hooks/useUsertrax";

export default function CTAButton({ children, variant, ...props }) {
  const { trackButtonClick } = useUsertrax();

  const handleClick = (e) => {
    trackButtonClick({
      button_text: children,
      button_variant: variant,
      page: window.location.pathname,
    });
  };

  return (
    <button onClick={handleClick} {...props}>
      {children}
    </button>
  );
}

Erweiterte Konfiguration

Custom Event Tracking

export const trackCustomEvent = (eventName, data = {}) => {
  const enhancedData = {
    ...data,
    timestamp: new Date().toISOString(),
    user_agent: navigator.userAgent,
    referrer: document.referrer,
    url: window.location.href,
  };

  trackEvent(eventName, enhancedData);
};

E-Commerce Integration

import { useUsertrax } from "./useUsertrax";

export const useEcommerceTracking = () => {
  const { trackEvent } = useUsertrax();

  const trackProductView = (product) => {
    trackEvent("product_viewed", {
      product_id: product.id,
      product_name: product.name,
      product_price: product.price,
      product_category: product.category,
    });
  };

  const trackAddToCart = (product, quantity = 1) => {
    trackEvent("product_added_to_cart", {
      product_id: product.id,
      product_name: product.name,
      product_price: product.price,
      quantity: quantity,
    });
  };

  const trackPurchase = (order) => {
    trackEvent("purchase", {
      order_id: order.id,
      total: order.total,
      currency: order.currency,
      items: order.items,
    });
  };

  return {
    trackProductView,
    trackAddToCart,
    trackPurchase,
  };
};

Fehlerbehebung

Events werden nicht gesendet: Überprüfe Browser Console auf Fehler und verifiziere API Key
Umgebungsvariablen funktionieren nicht: Stelle sicher, dass Variablen mit NEXT_PUBLIC_ beginnen
Server-side Rendering Probleme: Verwende useEffect für client-seitige Initialisierung
TypeScript Fehler: Füge Typdefinitionen für die usertrax Bibliothek hinzu

TypeScript Support

declare global {
  interface Window {
    usertrax: {
      push: (data: any) => void;
    };
  }
}

export interface UsertraxConfig {
  publicKey: string;
  scriptUrl?: string;
}

export interface ConversionData {
  event: string;
  id?: string;
  total?: number;
  currency?: string;
  user_data?: Record<string, any>;
  metadata?: Record<string, any>;
}