Personen & Kohorten

Events beschreiben Vorgänge. Personen beschreiben, wer sie ausgelöst hat — und Kohorten sind Gruppen von Personen nach Regeln, die du selbst festlegst: „Stammkunden“, „Warenkorbabbrecher der letzten 7 Tage“, „B2B-Kunden ohne Kauf“.

Eine Kohorte lässt sich als Kundenliste exportieren und bei Meta (Custom Audience) oder Google Ads (Customer Match) hochladen. Alles, was die Datei enthält, sind Hashes und Kundennummern — Klartext kennt Trackdolphin nicht.

Was eine Person ist

Eine Person je Shop ist der erste bekannte Wert dieser Reihe:

external_id — die Kundennummer deines Shops (Klartext, höchstens 128 Zeichen),
sonst em — die SHA-256-gehashte E-Mail,
sonst visitor_id — die zufällige Besucherkennung aus dem SDK-Cookie.

Solange nur die Besucherkennung bekannt ist, zählt die Person als „anonym“. Sobald ein Event Kundennummer oder E-Mail-Hash mitbringt, wird sie unter diesem Schlüssel geführt. Die anonymen Besuche davor erscheinen in ihrer Reise, weil die Besucherkennung dieselbe bleibt.

Es gibt keinen eigenen Personenspeicher. Erster und letzter Kontakt, Anzahl Käufe, Umsatz und Eigenschaften entstehen bei jeder Abfrage aus den Events. Löschst du die Events einer Person, ist auch die Person weg — es gibt keine zweite Kopie, die jemand vergessen könnte.

identify() im SDK

Das SDK kennt dafür einen eigenen Aufruf:

td.identify({
  email: "anna@example.com",   // wird vor dem Senden gehasht
  phone: "+49 171 2345678",    // ebenfalls — in beiden Telefon-Formaten
  externalId: "K-10042",       // die Kundennummer deines Shops, Klartext
  traits: { kundengruppe: "b2b", newsletter: true, bestellungen: 3 },
});

Das erzeugt ein Event vom Typ identify. Es ist weder Kauf noch Lead und geht an keine Werbeplattform — auch nicht an GA4. Es sagt nur: dieser Besucher ist diese Person, und das weiß der Shop über sie.

Ab dann setzt das SDK external_id automatisch an alle weiteren Events des Browsers, sodass Käufe und Seitenaufrufe derselben Person zugeordnet werden. Serverseitig gibst du external_id selbst mit.

Traits sind flache Angaben: Text, Zahl oder Wahrheitswert, höchstens 20 Schlüssel, Werte höchstens 256 Zeichen. Verschachtelte Objekte werden abgewiesen. Was der Shop zuletzt gemeldet hat, gilt — ein neuer identify()-Aufruf ersetzt den Stand, er ergänzt ihn nicht.

Regeln

Alle Regeln einer Kohorte sind optional und gelten zusammen (UND). Eine Kohorte ohne Regel sind alle Personen des Shops.

Regel	Bedeutung
`purchases_min`	mindestens so viele Käufe
`purchases_max`	höchstens so viele Käufe — `0` heißt „noch nie gekauft“
`revenue_min`	Mindestumsatz über alle Käufe (Shop-Währung)
`last_seen_days`	zuletzt aktiv innerhalb der letzten n Tage
`first_seen_days`	zum ersten Mal gesehen innerhalb der letzten n Tage (Neukunden)
`event_types`	hat mindestens eines dieser Events ausgelöst, z. B. `["add_to_cart"]`
`traits`	Eigenschaften aus `identify()`, die genau so gesetzt sein müssen

Beispiele:

Stammkunden: { "purchases_min": 2 }
Warenkorbabbrecher der Woche: { "event_types": ["add_to_cart"], "purchases_max": 0, "last_seen_days": 7 }
B2B ohne Kauf: { "traits": { "kundengruppe": "b2b" }, "purchases_max": 0 }

Gezählt werden ausschließlich Events der Umgebung production — ein Staging-Testkauf macht niemanden zum Stammkunden.

Über die API

text

GET    /api/shops/{shopId}/persons?limit=50&cursor=…
GET    /api/shops/{shopId}/persons/{key}
GET    /api/shops/{shopId}/cohorts
POST   /api/shops/{shopId}/cohorts            { "name": "…", "rules": { … } }
PUT    /api/shops/{shopId}/cohorts/{id}
DELETE /api/shops/{shopId}/cohorts/{id}
GET    /api/shops/{shopId}/cohorts/{id}/preview
GET    /api/shops/{shopId}/cohorts/{id}/export?format=csv

Authentifizierung wie überall: ein API-Schlüssel als Bearer-Token, siehe API. Im MCP-Server stehen dieselben Fähigkeiten als Werkzeuge persons_list, person_journey, cohorts_list, cohort_create, cohort_preview und cohort_export zur Verfügung — ein Agent kann also fragen: „Wie viele Kunden haben in den letzten 30 Tagen zweimal gekauft?“ und die Kohorte gleich anlegen.

Export für Meta und Google

Der Export liefert vier Spalten:

Spalte	Inhalt	Für
`em`	SHA-256 der E-Mail, Kleinbuchstaben	Meta, Google
`ph`	SHA-256 der Telefonnummer in E.164 ohne Plus	Meta
`ph_e164`	SHA-256 der Telefonnummer in E.164 mit Plus	Google Ads
`external_id`	Kundennummer, Klartext	Meta (`extern_id`)

Beim Hochladen ordnest du die Spalten den Feldern der Plattform zu und markierst sie als bereits gehasht. Personen ohne eines dieser Merkmale — also rein anonyme Besucher — fehlen in der Datei: Eine Zeile aus leeren Feldern könnte keine Plattform zuordnen.

Eine Datei enthält höchstens 100.000 Zeilen. Größere Kohorten teilst du über die Regeln auf — Kundenlisten werden bei beiden Plattformen ohnehin in Stücken hochgeladen.

Datenschutz

Nur Hashes. E-Mail und Telefon erreichen Trackdolphin ausschließlich als SHA-256. Es gibt keinen Weg zurück zum Klartext — auch nicht für uns. Die gekürzte Darstellung in der Personenliste dient dem Wiedererkennen, nicht dem Entschlüsseln.
Traits sind Kundenangaben. Was du in identify() mitgibst, ist deine Entscheidung und deine Verantwortung: Es sollte nur enthalten, was du für Zielgruppen tatsächlich brauchst. Keine Gesundheitsdaten, keine Freitextnotizen, keine Adressen.
Kohorten speichern Regeln, keine Mitglieder. Es gibt keine Mitgliederliste, die veralten oder vergessen werden könnte.
Löschung. Löschst du die Events einer Person (siehe Datenschutz), verschwindet sie aus jeder Kohorte und jedem künftigen Export. Bereits hochgeladene Kundenlisten löschst du bei der jeweiligen Plattform.
Einwilligung. Kundenlisten bei Werbeplattformen setzen eine Rechtsgrundlage voraus — in der Regel die Einwilligung der Person in Werbung. Trackdolphin prüft das nicht für dich; der Export ist ein Werkzeug, kein Freibrief.

#Personen & Kohorten

#Was eine Person ist

#identify() im SDK

#Regeln

#Über die API

#Export für Meta und Google