Dokumentation

Bevor Sie beginnen

• Ein Privatrak-Projekt für Ihre Website. Wie Sie eines anlegen, zeigt Erste Schritte.
• Next.js 13.4 oder neuer und React 18.2 oder neuer.
• Ihr Website-Schlüssel, also der Schlüssel vom Typ Ihre Website. Sie kopieren ihn unter Einstellungen › API-Schlüssel. Er kann nur Daten senden. Sie können ihn also gefahrlos in Ihre App schreiben.

Analytics in Ihre Next.js-App einbauen

1. Installieren Sie das Paket:

   npm install @privatrak/next

2. Tragen Sie Ihren Website-Schlüssel in .env.local ein, oder in die Umgebungseinstellungen Ihres Hosts:

   NEXT_PUBLIC_PRIVATRAK_API_KEY=your-website-key

3. Rendern Sie <Privatrak /> einmal im Root-Layout. Es zeigt nichts an und folgt Seitenwechseln von selbst:

   // app/layout.tsx
   import { Privatrak } from '@privatrak/next';
   
   export default function RootLayout({ children }: { children: React.ReactNode }) {
     return (
       <html lang="en">
         <body>
           <Privatrak />
           {children}
         </body>
       </html>
     );
   }

Beim Pages Router rendern Sie es stattdessen in pages/_app.tsx:

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { Privatrak } from '@privatrak/next';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Privatrak />
      <Component {...pageProps} />
    </>
  );
}

Next.js liest Werte mit NEXT_PUBLIC_ beim Build Ihrer App. Wenn Sie den Schlüssel ändern, bauen Sie die App deshalb erneut.

Ab dann erfasst Privatrak Seitenaufrufe, Klicks und abgeschickte Formulare.

Festlegen, was der Tracker erfasst

<Privatrak /> nimmt die Optionen des Trackers als Props:

<Privatrak autocapture={false} excludedUrls={['/admin/*']} traits={['beta']} />

Optionen, die Sie weglassen, folgen den Einstellungen Ihres Projekts unter Einstellungen › Tracker. Es gelten die Props des ersten Renderns, eine spätere Änderung bewirkt also nichts. Alle Optionen stehen in der Tracker-Referenz.

Aktionen im Code benennen

Fügen Sie einem Button oder Link data-track hinzu. Privatrak zeigt ihn dann als Feature, also als Namen für etwas, das Besucher auf Ihrer Website tun, hier signup-cta:

<button data-track="signup-cta" data-track-plan="pro">Sign up</button>

Um ein Event aus dem Code zu senden, importieren Sie track() aus @privatrak/next. Mit setTraits() geben Sie dem Besuch eine Liste von Traits, etwa einen Tarif:

'use client';
import { useEffect } from 'react';
import { track, setTraits } from '@privatrak/next';

export function CheckoutButton({ plan }: { plan: string }) {
  useEffect(() => {
    setTraits([plan]);
  }, [plan]);

  return <button onClick={() => track('checkout-completed', { plan })}>Buy</button>;
}

Rufen Sie beide in Client-Komponenten und Event-Handlern auf. Auf dem Server tun sie nichts. Weitere Beispiele finden Sie unter Im Code benennen.

KI-Dienste und Crawler melden

KI-Dienste wie ChatGPT und Claude lesen Ihre Seiten, ohne JavaScript auszuführen, deshalb sieht der Tracker sie nie. withPrivatrak() meldet ihre Anfragen von Ihrem Server aus, und die Seite KI-Dienste zeigt, wie oft jeder Dienst Ihre Seiten gelesen hat. Ihre Seiten werden wie zuvor ausgeliefert: Es ändert nie eine Antwort und lässt keinen Besucher warten.

Legen Sie proxy.ts neben app oder in src an. Mit Next.js 16 sieht sie so aus:

import { withPrivatrak } from '@privatrak/next/server';

export const proxy = withPrivatrak();

Mit Next.js 13 bis 15 nennen Sie die Datei middleware.ts und schreiben export default withPrivatrak();.

Der Proxy nutzt denselben Website-Schlüssel wie der Tracker.

Mit einem vorhandenen Proxy verwenden

Haben Sie schon einen Proxy oder eine Middleware, übergeben Sie sie. Ihre Antwort wird unverändert zurückgegeben:

import { NextResponse, type NextRequest } from 'next/server';
import { withPrivatrak } from '@privatrak/next/server';

export const proxy = withPrivatrak((request: NextRequest) => {
  if (request.nextUrl.pathname === '/old') {
    return NextResponse.redirect(new URL('/new', request.url));
  }
  return NextResponse.next();
});

Die Middleware einer Bibliothek umhüllen Sie genauso, zum Beispiel mit withPrivatrak(clerkMiddleware()).

Die Seiten behalten, die Crawler abfragen

Next.js führt den Proxy für jede Anfrage aus, solange config.matcher nichts anderes festlegt. Dieser Matcher überspringt Bilder, Skripte und andere Dateien und behält die Seiten, die Crawler abfragen:

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:png|jpg|jpeg|gif|webp|avif|svg|ico|css|js|woff2?)$).*)',
  ],
};

Lassen Sie robots.txt, Sitemaps wie sitemap.xml, llms.txt und .md-Dateien in Ihrem Matcher, denn Crawler fragen sie beim Namen an. Der Beispiel-Matcher aus der Next.js-Dokumentation lässt robots.txt und sitemap.xml aus, übernehmen Sie ihn also nicht. Privatrak zählt genau die Anfragen, für die Ihr Proxy läuft.

Schlüssel und Optionen für den Server festlegen

Der Proxy liest zuerst PRIVATRAK_API_KEY und danach NEXT_PUBLIC_PRIVATRAK_API_KEY. Nutzen Sie PRIVATRAK_API_KEY, wenn nur der Server den Schlüssel haben soll. Er wird gelesen, solange der Server läuft, eine Änderung braucht also keinen erneuten Build. Optionen übergeben Sie mit withPrivatrak(options), oder mit withPrivatrak(handler, options), wenn Sie einen eigenen Proxy haben:

Next.js selbst hosten

Bei Vercel und anderen Serverless-Hosts ist nichts weiter nötig. Die Meldung wird gesendet, bevor die Funktion endet, mit proxy.ts auf Node und mit middleware.ts in der Edge-Runtime.

Hosten Sie Next.js selbst hinter einem Reverse-Proxy, geben Sie den ursprünglichen Host-Header weiter und setzen Sie X-Forwarded-Proto. In nginx ist das proxy_set_header Host $host;. Sonst meldet Privatrak Ihre Seiten unter dem Namen Ihres Upstream-Servers.

Melden Sie Server-Anfragen schon auf anderem Weg, zum Beispiel mit einem Cloudflare Worker, nutzen Sie nur einen davon, sonst wird jede Anfrage doppelt gezählt. Server-Anfragen melden erklärt, wie.

Was Privatrak in Next.js erfasst

Im Browser erfasst Privatrak Seitenaufrufe, Klicks, abgeschickte Formulare und die Events, die Sie mit track() senden. Was Besucher in ein Formular eintippen, liest es nie. Es setzt keine Cookies, deshalb brauchen Sie keinen Cookie-Banner. Wie Besucher gezählt werden, erklärt Datenschutz.

Von Ihrem Server erhält Privatrak nur Anfragen bekannter Crawler, und nur für Seiten, robots.txt, Sitemaps, llms.txt und .md-Dateien. Zu jeder Anfrage sind das der User-Agent des Crawlers, die Seitenadresse und die Uhrzeit. Nichts über Ihre Besucher verlässt Ihren Server. Die Einzelheiten stehen unter Was Ihren Server verlässt.

Prüfen, ob es funktioniert

Seitenaufrufe prüfen

1. Öffnen Sie in Ihrem Browser eine Seite Ihrer Website.
2. Öffnen Sie in Privatrak Events und klicken Sie auf Events aktualisieren.

Ihr Seitenaufruf steht in der obersten Zeile, mit dem Typ Seitenaufruf. 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.

Anfragen von Crawlern prüfen

1. Rufen Sie eine Seite Ihrer Live-Website so auf, wie es ein KI-Dienst täte. Ersetzen Sie die Adresse durch Ihre eigene:

   curl -A "ChatGPT-User/1.0" https://example.com/

2. Öffnen Sie in Privatrak KI-Dienste und wechseln Sie zum Tab Alle Crawler.

ChatGPT-User (OpenAI) erscheint unter KI-Antworten mit 1 Anfrage. Diese Testanfrage zählt wie eine echte. Erscheint nichts, prüfen Sie, ob Ihr Website-Schlüssel gesetzt ist, ob die Domain Ihrer Website unter den erlaubten Domains steht, ob Ihr Matcher die Seite einschließt und ob kein Cache die Anfrage beantwortet hat.