Dokumentation

Erfahren Sie, wie Sie das Tracking-Tool verwenden

Videoreihe ansehenAcht kurze Videos zum gesamten Produkt, auf YouTube.

Benutzerdefinierte Events

Seitenaufrufe, Klicks und abgeschickte Formulare werden für Sie aufgezeichnet. Alles andere ist ein Custom Event: die Dinge, auf die es in Ihrem Produkt ankommt, die aber nicht daran hängen, dass jemand irgendwo klickt – eine Zahlung, die durchging, ein Video, das zu Ende gesehen wurde, ein Import, der auf halber Strecke scheiterte. Es gibt zwei Wege, so etwas aufzuzeichnen. Ein HTML-Attribut benennt etwas, das bereits auf der Seite steht, und braucht kein JavaScript. Die Funktion track() zeichnet etwas auf, hinter dem kein Element steht.

Wofür Sie das nutzen können

Erfassen, worauf es Ihnen wirklich ankommt: nicht den Klick auf „Bezahlen“, sondern die geglückte Zahlung, gesendet aus dem Code, der davon weiß.
Messen, was kein Element hat: eine Suche ohne Treffer, ein Video, das zu Ende läuft, ein Filter in einer Komponente, die die Seite nie neu lädt.
Die Aktionen zählen, die es nur bei Ihnen gibt: ein angelegtes Projekt, eine eingeladene Kollegin, ein exportierter Bericht.

HTML-Attribute

Setzen Sie ein data-track-Attribut auf ein Element, dann bekommen seine Klicks einen Namen. Dafür ist nichts weiter nötig: Der Tracker hört der ganzen Seite ohnehin zu.

Etwas mit data-track benennen

Der Wert des Attributs wird zum Namen. Ein Element mit data-track wird auch dann erfasst, wenn die automatische Erfassung von Klicks ausgeschaltet ist – so erfassen Sie eine Handvoll Dinge, ohne alles zu erfassen.

<button data-track="signup-cta">Sign Up Free</button>

Mit data-track-* Details mitgeben

Daraus werden die Attribute des Events. Das Präfix fällt weg, data-track-plan="pro" kommt also als plan: pro an, und Sie können beliebig viele davon setzen. Sie landen im selben Feld data_track_attrs wie das attrs-Objekt, das Sie an track() übergeben – die Werte, nach denen Sie später filtern und aufschlüsseln. Sie müssen auf demselben Element sitzen wie data-track selbst. Eines auf einem Kindelement wird nicht mitgenommen.

<button
  data-track="pricing-cta"
  data-track-plan="pro"
  data-track-interval="yearly"
>
  Upgrade to Pro
</button>

Der Klick auf das Symbol im Button

Die Leute klicken auf die Beschriftung oder das Symbol, nicht auf den Button. Landet ein Klick auf etwas ohne eigenen Namen, schaut der Tracker von dort nach außen und nimmt das erste data-track, das er findet. Standardmäßig schaut er drei Ebenen weit; data-walk-depth ändert das. Ein Attribut an einem Container benennt damit jeden Klick darin, und das Symbol müssen Sie nie auszeichnen.

<div data-track="feature-card" data-track-feature="analytics">
  <h3>Analytics</h3>
  <p>Track your metrics</p>
  <button>Learn more</button>  <!-- click here inherits data-track -->
</div>

Die Methode track()

window.tracker.track() steht auf jeder Seite bereit, auf der das Skript liegt. Sie erwartet zwei Argumente:

name (String, erforderlich): wie das Event heißt. Gespeichert als data_track – dasselbe Feld, das auch ein data-track-Attribut füllt. Ein Custom Event und ein getaggter Klick können also dasselbe Feature sein.
attrs (Objekt, optional): weitere Werte als Text. Sie landen in data_track_attrs, demselben Feld, das auch data-track-*-Attribute füllen.

Ein Beispiel

// Track a simple event
window.tracker.track("signup-completed");

// Track an event with attributes
window.tracker.track("plan-upgraded", {
  plan: "pro",
  interval: "yearly"
});

Was mit einem Custom Event passiert

Der Tracker baut ein Event mit dem Typ custom, der Seite, auf der Sie gerade sind, und der aktuellen Zeit und legt es in dieselbe Warteschlange wie alles andere. Es reist in denselben Stapeln und trägt dieselbe Session. Ein Aufruf mit leerem Namen tut überhaupt nichts, und zwar stillschweigend – prüfen Sie den Namen also, wenn er aus einer Variablen kommt.

Session-Traits

window.tracker.setTraits(["plan:pro", "role:admin"]) hängt Traits an den Besucher und nicht an ein einzelnes Event; alles, was danach gesendet wird, trägt sie. Nach diesen Traits filtern Sie im Dashboard. Der Aufruf ersetzt die Liste, statt sie zu ergänzen – übergeben Sie also jedes Mal den vollständigen Satz. Im Browser wird nichts abgelegt, jeder Seitenaufruf beginnt deshalb ohne Traits, bis Sie sie erneut setzen.

window.tracker.setTraits(["plan:enterprise", "role:admin"]);

Wann Sie was nehmen

Nehmen Sie ein data-track-Attribut, wenn:

Es um ein Element geht, auf das jemand klickt
Auch Leute ohne JavaScript-Kenntnisse Tracking ergänzen können sollen
Es im Markup sichtbar sein soll, direkt neben dem, was es misst

Nehmen Sie track(), wenn:

Nichts angeklickt wurde – ein Timer, eine Anfrage im Hintergrund, eine gescheiterte Zahlung
Die Werte erst zur Laufzeit feststehen
Erst gezählt werden soll, wenn etwas geklappt hat – nach der Prüfung oder in einem Callback

Nehmen Sie den Element Picker, wenn:

Sie den Code der Website nicht ändern können, zumindest nicht diese Woche
Jemand ohne technischen Hintergrund es einrichten muss
Das Element schon auf der Seite steht und nur einen Namen braucht – siehe Tracking ohne Code

Ab wann track() funktioniert

Das Objekt window.tracker existiert, sobald das Skript gelaufen ist, aufgezeichnet wird aber nichts, bevor der Tracker initialisiert ist. Mit dem defer-Script-Tag, das wir empfehlen, fallen diese beiden Zeitpunkte zusammen – Sie können track() also sofort aufrufen. Steht das Tag ohne defer im Kopf der Seite, wartet die Initialisierung, bis die Seite fertig geparst ist. Ein track()-Aufruf davor geht stillschweigend verloren – er wird nicht gepuffert, und gemeldet wird nichts. Nehmen Sie das empfohlene Snippet, oder rufen Sie track() zum ersten Mal nach der Initialisierung auf.

Den Tracker selbst starten

data-manual-init am Skript-Tag hält den Tracker davon ab, von selbst zu starten: Bis Sie window.tracker.init(config) aufrufen, wird nichts erfasst, auch nicht der erste Seitenaufruf. Verloren ist er deshalb nicht, nur verspätet: init() erfasst beim Ausführen selbst einen Seitenaufruf, und zwar für die Seite, auf welcher der Besucher in diesem Moment ist. Starten Sie den Tracker erst nach einem Seitenwechsel im Browser, wird die spätere Seite gezählt. Nehmen Sie das, wenn die Einstellungen erst zur Laufzeit feststehen – wenn Sie auf eine Einwilligungsentscheidung warten oder einen Schlüssel aus Ihrer eigenen Konfiguration lesen. Die Tracker-Referenz listet alles auf, was die Konfiguration annimmt.

<script src="https://api.privatrak.com/tracker.js" data-manual-init defer></script>
<script>
  window.tracker.init({
    apiKey: "your-public-key",
    apiHost: "https://api.privatrak.com",
    autocapture: false
  });
</script>

Beispiele

// After a successful purchase
window.tracker.track("purchase-completed", {
  plan: "starter",
  amount: "29"
});

// Feature toggle usage
window.tracker.track("feature-toggled", {
  feature: "dark-mode",
  enabled: "true"
});

// Search performed
window.tracker.track("search", {
  query: "pricing",
  results: "5"
});

Niemals die Identität einer Person in ein Attribut schreiben

Attributwerte werden genau so gespeichert, wie Sie sie senden. Nichts wird gekürzt, gehasht oder geprüft. Was in einem Attribut steht, liest also jeder wieder heraus, der Ihre Daten abfragen kann.

Senden Sie nichts, was auf eine einzelne Person zeigt. Das gilt für Konto-IDs, Benutzer-IDs, E-Mail-Adressen, Benutzernamen, Telefonnummern, Bestellnummern und Hashes davon. Eine gehashte Benutzer-ID ist weiterhin ein personenbezogener Wert: Dieselbe Person bekommt jedes Mal denselben Hash, und mehr braucht es nicht.

Das ist wichtig, weil es genau die Eigenschaft aushebelt, wegen der Sie vermutlich hier sind. Privatrak speichert weder IP-Adresse noch User-Agent, und die abgeleitete Session-ID wird jede Nacht aus einem neuen Schlüssel gebildet, sodass sich die Aktivität einer Besucherin nicht über Tage hinweg zusammenführen lässt. Ein einziges gleichbleibendes personenbezogenes Attribut stellt diese Verbindung wieder her: Sessions lassen sich aneinanderreihen und die gesamte Historie einer Person aus den Events rekonstruieren.

Eine einfache Faustregel

Gut: ein Wert aus einer kurzen, festen Liste, den viele Personen teilen: plan: "pro", interval: "yearly", result: "error", step: "3".
Schlecht: ein Wert, der bei fast jedem Event anders ist oder zu einem einzelnen Konto gehört: user_id: "4711", email: "ada@example.com", cart_id: "c_8f3a…", uid_hash: "9b1c…".

Wenn Sie Gruppen vergleichen möchten, senden Sie die Gruppe und nicht das einzelne Mitglied: plan: "pro" sagt Ihnen, was Sie wissen wollten, während account_id nichts darüber hinaus verrät, dafür aber jede Person nachverfolgbar macht.

Das gilt für jedes Attribut

Es macht keinen Unterschied, auf welchem Weg Sie eines setzen. Ein data-track-*-Attribut und das attrs-Objekt landen im selben Feld, und für beide gilt dieselbe Regel.

Die PII-Einstellungen unter Datenschutz & Sicherheit helfen hier nicht. Diese Einstellungen bereinigen ausschließlich URL-Pfadsegmente und URL-Parameter, und sie laufen im Tracker, bevor das Event gesendet wird; ein veränderter oder selbst geschriebener Client umgeht sie also vollständig. Attribute werden nie geprüft.

Ihre Events wiederfinden

Benutzerdefinierte Events stehen mit allem anderen auf der Seite Events. Filtern Sie nach dem Typ custom, um nur Ihre zu sehen, und grenzen Sie dann weiter über den Namen oder eines der angehängten Attribute ein. Zu den Zahlen oben auf dieser Seite gehört eine für benutzerdefinierte Events – das ist der schnellste Weg, um zu bestätigen, dass ein neuer Aufruf überhaupt ankommt.