Dokumentation

Ihren Website-Schlüssel holen

Beide Wege brauchen Ihren Website-Schlüssel. Auf der Seite Einrichtung steht er schon im Skript-Tag. Sie können auch unter Einstellungen › API-Schlüssel mit Schlüssel erstellen einen anlegen und dabei den Typ Ihre Website wählen. Dieser Schlüssel kann nur Daten senden. Sie können ihn also gefahrlos in Ihre Seite schreiben.

Mit dem Skript-Tag

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

Setzen Sie das Tag in den <head> Ihres HTML. Besteht Ihre Website aus einzelnen Seiten, gehört es auf jede Seite, die erfasst werden soll. Behalten Sie defer bei.

Wo das Tag hingehört:

• React mit Vite sowie Vue: index.html im Projektordner.
• Create React App: public/index.html.
• Angular: src/index.html.
• SvelteKit: src/app.html.
• Next.js: die Komponente Script im Root-Layout, wie unten gezeigt. Beim Pages Router gehört sie in pages/_app.tsx. Das Paket @privatrak/next ist der einfachere Weg: Auf Next.js einbinden.
• Nuxt: app.head.script in nuxt.config.ts, mit data-api-key und defer: true, wie unten gezeigt. Das Modul @privatrak/nuxt ist der einfachere Weg: Auf Nuxt einbinden.

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://api.privatrak.com/tracker.js"
          data-api-key="your-website-key"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://api.privatrak.com/tracker.js',
          'data-api-key': 'your-website-key',
          defer: true,
        },
      ],
    },
  },
});

Beim Skript-Tag kennt TypeScript window.tracker nicht. Fügen Sie Ihrem Projekt diese Deklaration hinzu:

export {};

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

Mit dem npm-Paket

Installieren Sie @privatrak/tracker und rufen Sie init() einmal im Browser auf, so früh wie möglich. Übergeben Sie apiKey und apiHost genau wie gezeigt.

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

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

track('signup-completed');

Ab dann werden Seitenaufrufe, Klicks und abgeschickte Formulare erfasst, auch der erste Seitenaufruf. Auf einem Server tut init() nichts. Sie können es also auch in Code importieren, der dort gerendert wird. Die Typen bringt das Paket selbst mit.

React

Rufen Sie init() in der Datei auf, die Ihre App startet, und zwar vor dem Rendern: src/main.tsx bei Vite, src/index.tsx bei Create React App.

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

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

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

Next.js

Das Paket @privatrak/next ist der einfachere Weg: Es startet den Tracker für Sie und meldet außerdem KI-Crawler von Ihrem Server aus. Auf Next.js einbinden zeigt die Schritte. Möchten Sie stattdessen @privatrak/tracker nutzen, starten Sie ihn in einer kleinen Client-Komponente und rendern diese einmal im Root-Layout.

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

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

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

  return null;
}

Mit dem Pages Router rendern Sie dieselbe Komponente in pages/_app.tsx.

Vue

Rufen Sie init() in src/main.ts auf, bevor die App startet.

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

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

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

Nuxt

Das Modul @privatrak/nuxt ist der einfachere Weg: Es startet den Tracker für Sie, stellt useTracker() bereit und meldet außerdem KI-Crawler von Ihrem Server aus. Auf Nuxt einbinden zeigt die Schritte. Möchten Sie stattdessen @privatrak/tracker nutzen, legen Sie in app/plugins ein Plugin an, dessen Dateiname auf .client.ts endet. Nuxt führt es nur im Browser aus. Bei Nuxt 3 heißt der Ordner plugins.

// app/plugins/privatrak.client.ts
import { init } from '@privatrak/tracker';

export default defineNuxtPlugin(() => {
  init({
    apiKey: 'your-website-key',
    apiHost: 'https://api.privatrak.com',
  });
});

Angular

Rufen Sie init() in src/main.ts auf, bevor die Anwendung startet. track() importieren Sie in jeder Komponente, die es braucht.

// src/main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { init } from '@privatrak/tracker';
import { AppComponent } from './app/app.component';
import { appConfig } from './app/app.config';

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

bootstrapApplication(AppComponent, appConfig);

Svelte und SvelteKit

Rufen Sie init() im Root-Layout innerhalb von onMount auf, damit es im Browser läuft.

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

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

<slot />

Prüfen, ob es funktioniert

Öffnen Sie eine Seite Ihrer Website und danach Events in Privatrak. Ihr Seitenaufruf erscheint nach wenigen Sekunden. Kommt nichts an, öffnen Sie die Konsole Ihres Browsers. Der Tracker schreibt dort, was schiefgegangen ist, und unter Wenn nichts gesendet wird steht, was Sie tun können.

Von Ihrem Server

Um etwas zu erfassen, das nie in einem Browser passiert, senden Sie es an POST /api/events, mit Ihrem Website-Schlüssel im Header X-API-Key. Jedes Event braucht event_type, page_url und timestamp, und eine Anfrage nimmt bis zu 100 Events an. Diese Gruppe von Events können Sie mit einer batch_id benennen, einer UUID. Verwenden Sie für jede Gruppe eine neue ID und bei jedem erneuten Senden derselben Gruppe dieselbe. Kam eine Anfrage bei Privatrak an, aber die Antwort nicht bei Ihnen, senden Sie sie innerhalb von 1 Stunde erneut, ohne dass die Events doppelt gezählt werden. Danach zählt dieselbe ID die Events erneut. Verwenden Sie eine ID nie für andere Events, denn Privatrak speichert diese Events nicht.

curl -X POST https://api.privatrak.com/api/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-website-key" \
  -d '{
    "events": [{
      "event_type": "custom",
      "data_track": "invoice-paid",
      "page_url": "https://example.com/billing",
      "timestamp": "2026-01-15T10:30:00Z"
    }]
  }'

Privatrak zählt alle Events von einem Server als einen Besucher pro Tag.

Events von Ihrem Server werden so gezählt, wie Sie sie senden, mit jedem beliebigen HTTP-Client.