Dokumentation

Aus npm, mit einem Bundler

Wenn Ihre Website mit einem Bundler gebaut wird, können Sie den Tracker installieren, statt ein Skript-Tag zu laden. npm install @privatrak/tracker liefert dieselben drei Funktionen, die das Skript an window hängt, als gewöhnliche Importe.

import { init, track } from '@privatrak/tracker';

init({
  apiKey: 'your-public-key',
  apiHost: 'https://api.privatrak.com',
});

track('signup-completed');

Hier startet nichts von selbst. Das Skript-Tag liest seine Einstellungen von den eigenen Attributen und startet sich selbst. Ein Import hat kein Tag, das er lesen könnte – rufen Sie deshalb einmal init() auf, so früh in Ihrer Anwendung wie möglich. Geben Sie neben apiKey auch apiHost an: Ohne src eines Skript-Tags kann der Tracker die Adresse nicht selbst ermitteln. Fehlt der Schlüssel, meldet er Missing apiKey. Events will not be sent. und hört auf. Ab dem Moment, in dem init() läuft, werden Seitenaufrufe, Klicks und abgeschickte Formulare genauso erfasst wie mit dem Skript-Tag – einschließlich eines Seitenaufrufs für die Seite, auf der es läuft. Der erste geht also nicht verloren, wenn Sie spät starten.

init() tut nichts, wenn es keinen Browser gibt – Sie können es also gefahrlos in Code importieren, der auch auf einem Server gerendert wird. Ausgeführt werden muss es aber im Browser, sonst wird nichts erfasst. Rufen Sie es dort auf, wo Ihr Framework seine clientseitige Einrichtung erledigt. Ein zweiter Aufruf schadet nicht: Er wird mit einer Warnung ignoriert. Ein Unterschied zum ausgelieferten Skript: Der npm-Build bringt den Element Picker gleich mit, sodass das Auswählen von Elementen ohne zusätzlichen Download funktioniert.

Das Paket bringt seine eigenen Typdefinitionen mit, init(), track() und setTraits() sind also für Sie typisiert. Es gibt nichts, was Sie einer .d.ts hinzufügen müssten, und kein globales Objekt zu beschreiben.

React

Rufen Sie init() in der Datei auf, die Ihre App einhängt, bevor gerendert wird – src/main.tsx in einem Vite-Projekt, src/index.tsx unter Create React App. Alles Weitere läuft von allein.

// src/main.tsx
import { init } from '@privatrak/tracker';
import { createRoot } from 'react-dom/client';
import App from './App';

init({
  apiKey: 'your-public-key',
  apiHost: 'https://api.privatrak.com',
});

createRoot(document.getElementById('root')!).render(<App />);

Next.js

Next.js rendert auf dem Server, init() muss also in einer Client-Komponente laufen. Bauen Sie eine kleine, die nichts anderes tut als den Tracker zu starten, und rendern Sie sie einmal aus dem Root-Layout.

// app/tracker.tsx
'use client';

import { useEffect } from 'react';
import { init } from '@privatrak/tracker';

export function Tracker() {
  useEffect(() => {
    init({
      apiKey: 'your-public-key',
      apiHost: 'https://api.privatrak.com',
    });
  }, []);

  return null;
}

Mit dem Pages Router rufen Sie init() stattdessen in _app.tsx innerhalb eines useEffect auf. Dieselbe Komponente funktioniert dort ebenso.

Nuxt

Nuxt bekommt ein Modul statt eines Skript-Tags. Installieren Sie @privatrak/nuxt, tragen Sie es bei den Modulen ein und legen Sie die Einstellungen unter den Schlüssel tracker. Dort wird jede Option von TrackerInitConfig angenommen, und das Modul startet den Tracker im Browser für Sie. Geben Sie apiHost ausdrücklich an: Ohne Script-Tag, das gelesen werden könnte, hat das Modul nichts, woraus es die Adresse ableiten kann.

export default defineNuxtConfig({
  modules: ['@privatrak/nuxt'],
  tracker: {
    apiKey: 'your-public-key',
    apiHost: 'https://api.privatrak.com',
  },
});

Das Modul registriert außerdem ein Composable useTracker(), das wie Nuxts eigene automatisch importiert wird. Es gibt track und setTraits zurück:

<script setup>
const { track, setTraits } = useTracker();

track('button-clicked', { page: 'home' });
setTraits(['plan:pro']);
</script>

Vue

Rufen Sie init() in src/main.ts auf, bevor die App eingehängt wird.

// src/main.ts
import { init } from '@privatrak/tracker';
import { createApp } from 'vue';
import App from './App.vue';

init({
  apiKey: 'your-public-key',
  apiHost: 'https://api.privatrak.com',
});

createApp(App).mount('#app');

Angular

Rufen Sie init() in src/main.ts auf, bevor die Anwendung startet. Um den Tracker aus Komponenten zu erreichen, kapseln Sie die importierten Funktionen in einem Service, statt sie in jeder Komponente zu importieren.

// src/app/tracker.service.ts
import { Injectable } from '@angular/core';
import { track, setTraits } from '@privatrak/tracker';
import type { DataTrackAttrs } from '@privatrak/tracker';

@Injectable({ providedIn: 'root' })
export class TrackerService {
  track(name: string, attrs?: DataTrackAttrs): void {
    track(name, attrs);
  }

  setTraits(traits: string[]): void {
    setTraits(traits);
  }
}

Svelte und SvelteKit

Rufen Sie init() im Root-Layout innerhalb von onMount auf, damit es im Browser läuft und nicht, während die Seite auf dem Server gerendert wird.

<!-- src/routes/+layout.svelte -->
<script>
  import { onMount } from 'svelte';
  import { init } from '@privatrak/tracker';

  onMount(() => {
    init({
      apiKey: 'your-public-key',
      apiHost: 'https://api.privatrak.com',
    });
  });
</script>

<slot />

Mit einem Skript-Tag

Nichts davon setzt das Paket voraus. Wenn Sie keine Abhängigkeit aufnehmen wollen, den Tracker aus Ihrem Bundle heraushalten möchten oder gar keinen Build-Schritt haben, laden Sie stattdessen das Skript. Es startet sich selbst, liest seine Einstellungen aus den eigenen Attributen und ermittelt die API-Adresse aus seinem src – ein init()-Aufruf entfällt also. Behalten Sie das defer: Damit baut der Browser erst die Seite fertig.

<script
  src="https://api.privatrak.com/tracker.js"
  data-api-key="your-public-key"
  defer
></script>

Das Tag gehört in den <head> Ihres HTML – und zwar jeder Seite, die erfasst werden soll, wenn Ihre Website aus einzelnen Seiten besteht. Das ist index.html im Wurzelverzeichnis eines Vite-Projekts, public/index.html unter Create React App, index.html bei Vue, src/index.html bei Angular und src/app.html bei SvelteKit. React rendert diese Datei nie neu, das Tag bleibt also für die Lebensdauer der App stehen. Bei Next.js gibt es keine HTML-Datei zum Bearbeiten: Nehmen Sie die Script-Komponente im Root-Layout mit strategy="afterInteractive", wodurch das Skript läuft, sobald die Seite benutzbar ist, und der erste Seitenaufruf dann erfasst wird – oder in _app.tsx unter dem Pages Router.

Das Tag hängt den Tracker an window, wo TypeScript ihn nicht sieht. Das ist der eine Fall, in dem Sie ihn selbst beschreiben müssen – beim npm-Paket oben ist davon nichts nötig:

export {};

declare global {
  interface Window {
    tracker: {
      init: (config?: Record<string, unknown>) => void;
      track: (name: string, attrs?: Record<string, string>) => void;
      setTraits: (traits: string[]) => void;
    };
  }
}

Von Ihrem eigenen Server

Events lassen sich direkt an POST /api/events schicken, mit einem X-API-Key-Header – so erfassen Sie etwas, das nie in einem Browser passiert. Nehmen Sie auch hier einen öffentlichen Schlüssel, obwohl der Aufruf von Ihrem Server kommt. Ein öffentlicher Schlüssel kann nur Events senden und Tracker-Einstellungen abrufen und richtet deshalb den geringsten Schaden an, wenn er nach außen gelangt – und es ist ohnehin die einzige Art, die Sie derzeit anlegen können.

curl -X POST https://api.privatrak.com/api/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-public-key" \
  -d '{
    "events": [{
      "event_type": "custom",
      "data_track": "server-event",
      "page_url": "https://example.com/pricing?utm_source=newsletter",
      "timestamp": "2026-01-15T10:30:00Z"
    }]
  }'