@usertrax/tracker

Ein leichtgewichtiger JavaScript-Tracker für Conversion-Tracking und A/B-Testing mit Privacy-First-Ansatz.

🚀 Neue modulare Struktur

Der UserTrax Tracker wurde in eine modulare Struktur umorganisiert, um sowohl eine kompakte Web-Version als auch eine flexible NPM-Package-Version zu unterstützen, ohne Code-Duplikation.

📁 Detaillierte Struktur-Dokumentation

📦 Versionen

🌐 Web-Version (tracker.js)

Für einfache Websites mit einem Script-Tag

<script src="https://usertrax.io/cvs.js" data-key="YOUR_KEY"></script>
<script>
  window.usertrax.push({
    event: 'purchase',
    total: 99.99,
    currency: 'EUR',
  });
</script>

📦 NPM-Package-Version (tracker.esm.js)

Für moderne Web-Apps mit Build-Tools

import UserTraxTracker from '@usertrax/tracker';

const tracker = new UserTraxTracker({
  endpoint: 'https://api.usertrax.io/api/tracker/conversion',
  enableABTesting: true,
});

await tracker.init();
tracker.trackConversion({
  event: 'purchase',
  total: 99.99,
  currency: 'EUR',
});

🎯 Features

• Privacy-friendly: No cookies required
• A/B Testing: Built-in A/B testing support
• Cross-domain tracking: Track users across multiple domains
• Conversion tracking: Track purchases, signups, and custom events
• Session management: Automatic session tracking
• Engagement metrics: Scroll depth, time on page, clicks
• UTM parameter tracking: Automatic UTM parameter capture
• Ad platform integration: Google Ads, Facebook, Microsoft Ads, TikTok

Installation

NPM Package

npm install @usertrax/tracker

CDN (Script Tag)

<script src="https://usertrax.io/cvs.js" data-key="YOUR_AUTH_KEY"></script>

Schnellstart

1. NPM Package Integration

import UserTrax from '@usertrax/tracker';

// Initialisieren
UserTrax.init();

// Conversion tracken
UserTrax.track('purchase', {
  total: 99.99,
  currency: 'EUR',
  id: 'order_123',
});

2. Script Tag Integration

<script src="https://usertrax.io/cvs.js" data-key="YOUR_AUTH_KEY"></script>

API Referenz

Konfiguration

const config = {
  endpoint: 'https://api.usertrax.io/api/tracker/conversion',
  sessionEndpoint: 'https://api.usertrax.io/api/tracker/session',
  pageviewEndpoint: 'https://api.usertrax.io/api/tracker/pageview',
  autoTrack: true,
  enableABTesting: true,
  enableCrossDomainTracking: true,
  crossDomainParamName: 'uxs',
  crossDomainDomains: [],
};

Core Methods

init(config)

Initialisiert den Tracker mit Konfiguration.

UserTrax.init();

track(event, data)

Trackt ein Conversion-Event.

UserTrax.track('purchase', {
  total: 99.99,
  currency: 'EUR',
  id: 'order_123',
});

trackConversion(data)

Trackt ein vollständiges Conversion-Event.

UserTrax.trackConversion({
  event: 'purchase',
  total: 99.99,
  currency: 'EUR',
  id: 'order_123',
  metadata: {
    product: 'premium_plan',
    source: 'landing_page',
  },
});

A/B Testing

getVariant(testKey)

Holt die aktuelle Variante für einen A/B-Test.

const variant = UserTrax.getVariant('button_color');
// Returns: 'red' | 'blue' | null

getAssignments()

Holt alle A/B-Test-Zuweisungen.

const assignments = UserTrax.getAssignments();
// Returns: { 'button_color': 'red', 'headline': 'blue' }

applyElementVisibility()

Wendet A/B-Test-Sichtbarkeit auf HTML-Elemente an.

UserTrax.applyElementVisibility();

Session Management

getSessionId()

Holt die aktuelle Session-ID.

const sessionId = UserTrax.getSessionId();

refreshSession()

Erstellt eine neue Session-ID.

UserTrax.refreshSession();

Funnel Tracking

trackFunnel(event)

Trackt ein Funnel-Event.

UserTrax.trackFunnel({
  funnel_id: 'checkout_funnel',
  step_number: 1,
  step_name: 'cart_view',
  event_name: 'page_view',
});

trackFunnelBatch(events)

Trackt mehrere Funnel-Events in einem Batch.

UserTrax.trackFunnelBatch([
  {
    funnel_id: 'checkout_funnel',
    step_number: 1,
    step_name: 'cart_view',
  },
  {
    funnel_id: 'checkout_funnel',
    step_number: 2,
    step_name: 'checkout_form',
  },
]);

Utility Methods

getAttribution()

Holt Attribution-Daten (UTM, Click IDs).

const attribution = UserTrax.getAttribution();
// Returns: { gclid: '...', utm_source: 'google', ... }

getDeviceInfo()

Holt Geräte-Informationen.

const deviceInfo = UserTrax.getDeviceInfo();
// Returns: { deviceType: 'desktop', browser: 'Chrome', os: 'macOS' }

debug(enabled)

Aktiviert/Deaktiviert Debug-Modus.

UserTrax.debug(true);

Helper Methods

createTracker(event, defaultData)

Erstellt einen wiederverwendbaren Tracker.

const purchaseTracker = UserTrax.createTracker('purchase', {
  currency: 'EUR',
  source: 'website',
});

// Verwendung
purchaseTracker({ total: 99.99, id: 'order_123' });

trackForms(selector, event)

Trackt automatisch Formular-Submissions.

UserTrax.trackForms('form', 'form_submit');

trackButtons(selector, event)

Trackt automatisch Button-Klicks.

UserTrax.trackButtons('button, .btn', 'button_click');

trackExternalLinks(event)

Trackt automatisch externe Link-Klicks.

UserTrax.trackExternalLinks('external_link_click');

HTML Integration

Automatisches Conversion-Tracking

<a
  href="/checkout"
  data-usertrax="purchase"
  data-usertrax-total="99.99"
  data-usertrax-currency="EUR"
>
  Kaufen
</a>

A/B Testing mit HTML

<!-- Variante A -->
<div data-usertrax-ab-test-group="button_test" data-usertrax-ab-test-variant="red">
  <button style="background: red;">Kaufen</button>
</div>

<!-- Variante B -->
<div data-usertrax-ab-test-group="button_test" data-usertrax-ab-test-variant="blue">
  <button style="background: blue;">Kaufen</button>
</div>

<!-- Fallback -->
<div data-usertrax-ab-test-group="button_test" data-usertrax-ab-test-fallback>
  <button style="background: gray;">Kaufen</button>
</div>

Cross-Domain Tracking

UserTrax.init({
  enableCrossDomainTracking: true,
  crossDomainParamName: 'uxs',
  crossDomainDomains: ['example.com', 'shop.example.com'],
});

Framework Integration

React

import { useEffect } from 'react';
import UserTrax from '@usertrax/tracker';

function App() {
  useEffect(() => {
    UserTrax.init();
  }, []);

  const handlePurchase = () => {
    UserTrax.track('purchase', {
      total: 99.99,
      currency: 'EUR',
    });
  };

  return <button onClick={handlePurchase}>Kaufen</button>;
}

Vue.js

import { onMounted } from 'vue';
import UserTrax from '@usertrax/tracker';

export default {
  setup() {
    onMounted(() => {
      UserTrax.init();
    });

    const handlePurchase = () => {
      UserTrax.track('purchase', {
        total: 99.99,
        currency: 'EUR',
      });
    };

    return { handlePurchase };
  },
};

Next.js

// pages/_app.js
import { useEffect } from 'react';
import UserTrax from '@usertrax/tracker';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    UserTrax.init();
  }, []);

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

export default MyApp;

Datenschutz

• Keine Cookies: Verwendet sessionStorage statt Cookies
• GDPR-konform: Keine personenbezogenen Daten ohne Einwilligung
• Opt-out: Kann über autoTrack: false deaktiviert werden
• Privacy-First: Minimale Datensammlung, maximale Privatsphäre

Browser-Unterstützung

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• IE 11+ (mit Polyfills)

Lizenz

MIT License - siehe LICENSE Datei für Details.

Support

• 📧 Email: [email protected]
• 📖 Dokumentation: https://usertrax.io/docs