@usertrax/tracker/README.md

Privacy-friendly conversion tracking and A/B testing script for UserTrax

# @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](README_STRUCTURE.md)**

## 📦 Versionen

### 🌐 Web-Version (tracker.js)

**Für einfache Websites mit einem Script-Tag**

```html
<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**

```javascript
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

```bash
npm install @usertrax/tracker
```

### CDN (Script Tag)

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

## Schnellstart

### 1. NPM Package Integration

```javascript
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

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

## API Referenz

### Konfiguration

```javascript
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.

```javascript
UserTrax.init();
```

#### `track(event, data)`

Trackt ein Conversion-Event.

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

#### `trackConversion(data)`

Trackt ein vollständiges Conversion-Event.

```javascript
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.

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

#### `getAssignments()`

Holt alle A/B-Test-Zuweisungen.

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

#### `applyElementVisibility()`

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

```javascript
UserTrax.applyElementVisibility();
```

### Session Management

#### `getSessionId()`

Holt die aktuelle Session-ID.

```javascript
const sessionId = UserTrax.getSessionId();
```

#### `refreshSession()`

Erstellt eine neue Session-ID.

```javascript
UserTrax.refreshSession();
```

### Funnel Tracking

#### `trackFunnel(event)`

Trackt ein Funnel-Event.

```javascript
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.

```javascript
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).

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

#### `getDeviceInfo()`

Holt Geräte-Informationen.

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

#### `debug(enabled)`

Aktiviert/Deaktiviert Debug-Modus.

```javascript
UserTrax.debug(true);
```

### Helper Methods

#### `createTracker(event, defaultData)`

Erstellt einen wiederverwendbaren Tracker.

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

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

#### `trackForms(selector, event)`

Trackt automatisch Formular-Submissions.

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

#### `trackButtons(selector, event)`

Trackt automatisch Button-Klicks.

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

#### `trackExternalLinks(event)`

Trackt automatisch externe Link-Klicks.

```javascript
UserTrax.trackExternalLinks('external_link_click');
```

## HTML Integration

### Automatisches Conversion-Tracking

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

### A/B Testing mit HTML

```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

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

## Framework Integration

### React

```javascript
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

```javascript
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

```javascript
// 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](LICENSE) Datei für Details.

## Support

- 📧 Email: support@usertrax.io
- 📖 Dokumentation: https://usertrax.io/docs