Überblick
Benutzerdefinierte Ereignisse erfassen Aktionen von Nutzern aus externen Systemen (E-Commerce, CRM, Analyse). Sie erscheinen im Kontaktverlauf, und mit ihren Zielen bilden Sie RFM-Segmente (Recency, Frequency, Monetary).
Kontaktverlauf
Jedes benutzerdefinierte Ereignis legt einen Eintrag im Kontaktverlauf an, sodass Sie die gesamte Geschichte der Interaktionen eines Kontakts sehen:
Jedes Ereignis zeigt seinen event_name als Typ des Verlaufseintrags (z. B. „order.completed“, „subscription.started“). Das Feld properties speichert zusätzlichen Kontext, der in den Details des Verlaufseintrags sichtbar ist.
Zieltypen
Segmente bauen auf Zielen auf. Jedes Ereignis kann ein Ziel erfassen:
| Typ | Anwendungsfall | goal_value |
|---|---|---|
purchase | E-Commerce-Bestellungen, Einmalzahlungen | Erforderlich |
subscription | SaaS-Abonnements, Mitgliedschaften | Erforderlich |
lead | Kontaktformulare, Demo-Anfragen | Optional |
signup | Kontoregistrierungen | Optional |
booking | Termine, Beratungen | Optional |
trial | Aktivierungen kostenloser Testphasen | Optional |
other | Eigene Conversion-Ereignisse | Optional |
RFM-Segmente bilden
Die RFM-Analyse (Recency, Frequency, Monetary) findet Ihre besten Kunden. Verwenden Sie im Segment-Builder Bedingungen vom Typ Ziel:
Monetär: Gesamtausgaben
Wählen Sie den Zieltyp Kauf und die Aggregation Summe und legen Sie dann einen Mindestwert fest, um Kunden mit hohen Ausgaben zu finden.
Häufigkeit: Anzahl der Käufe
Wählen Sie den Zieltyp Kauf und die Aggregation Anzahl und legen Sie dann eine Mindestzahl fest, um Wiederkäufer zu finden.
Aktualität: Aktuelle Aktivität
Verwenden Sie den Zeitraumfilter „in den letzten X Tagen“, um Kunden mit aktuellen Käufen zu finden.
Beispiele für RFM-Segmente
- VIP-Kunden: Ausgaben ab 1000 $ UND ab 5 Bestellungen UND Kauf in den letzten 60 Tagen
- Gefährdete Kunden mit hohem Wert: Ausgaben ab 500 $ UND kein Kauf in 90 Tagen
- Neue Kunden mit hohem Potenzial: Erster Kauf über 200 $ in den letzten 30 Tagen
Aggregationsoptionen
| Option | Beschreibung |
|---|---|
| Summe | Summe aller Zielwerte (Gesamtausgaben) |
| Anzahl | Anzahl der Ereignisse (Zahl der Bestellungen) |
| Durchschnitt | Durchschnittlicher Zielwert (durchschnittlicher Bestellwert) |
| Minimum | Kleinster Zielwert |
| Maximum | Größter Zielwert |
Zeitraumoptionen
| Option | Beschreibung |
|---|---|
| Jederzeit | Alle historischen Daten |
| In den letzten X Tagen | Gleitendes Zeitfenster |
| Im Datumsbereich | Bestimmter Zeitraum |
| Vor Datum | Historischer Stichtag |
| Nach Datum | Seit einem bestimmten Datum |
Ereignisse erfassen
Einzelnes Ereignis
curl -X POST "https://your-instance.com/api/customEvents.upsert" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"email": "customer@example.com",
"event_name": "order.completed",
"external_id": "order_12345",
"properties": {
"items": ["Product A", "Product B"],
"currency": "USD"
},
"goal_type": "purchase",
"goal_value": 149.99
}'
Stapelimport
Importieren Sie bis zu 50 Ereignisse auf einmal:
curl -X POST "https://your-instance.com/api/customEvents.import" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"events": [
{
"email": "user1@example.com",
"event_name": "order.completed",
"external_id": "order_001",
"goal_type": "purchase",
"goal_value": 99.99
},
{
"email": "user2@example.com",
"event_name": "order.completed",
"external_id": "order_002",
"goal_type": "purchase",
"goal_value": 249.99
}
]
}'
Format von Ereignisnamen
Ereignisnamen müssen kleingeschrieben sein und dürfen Buchstaben, Ziffern, Punkte, Unterstriche, Bindestriche oder Schrägstriche enthalten:
order.completedsubscription/startedform_submituser-signup
Hinweis
Ziele, die die Web-Analyse erfasst, gelangen nach einer engeren Regel in den Kontaktverlauf: nur ASCII-Buchstaben, Ziffern, Punkte und Schrägstriche, alles andere (auch Bindestriche und Zeichen mit Akzent) wird durch einen Unterstrich ersetzt. Ein Web-Ziel namens user-signup kommt als user_signup an. Wenn Sie dasselbe Ereignis über beide Wege senden, wählen Sie einen Namen, der beide Regeln übersteht.
Rückerstattungen behandeln
Verwenden Sie für Rückerstattungen einen negativen goal_value, damit die LTV-Berechnungen stimmen:
{
"email": "customer@example.com",
"event_name": "order.refunded",
"external_id": "refund_12345",
"goal_type": "purchase",
"goal_value": -50.00
}
Berechtigungen
Benutzerdefinierte Ereignisse haben keine eigene Berechtigung, sie unterliegen Kontakte. Ein Ereignis zu erfassen oder zu importieren braucht bei Kontakte Schreiben, es zu lesen Gelesen. Wer Lesezugriff auf Kontakte vergibt, öffnet damit auch die zu Ihren Kontakten erfassten Ereignisse und den Kontaktverlauf, den sie speisen. Siehe Admins & API-Schlüssel.
Hinweise
customEvents.upsertlegt den Kontakt an, wenn es keinen Kontakt mit dieser E-Mail-Adresse gibt.customEvents.importlegt keinen Kontakt an- Ereignisse werden nur aktualisiert, wenn
occurred_atneuer ist als der vorhandene Wert - Soft Delete durch Setzen von
deleted_at(aufnullsetzen, um wiederherzustellen) - Nur ein neues Ereignis (eine neue
external_id) startet die Automatisierungen, die durch seinen Namen ausgelöst werden; seit 44.0 tut das eine Aktualisierung, ein Soft Delete oder eine Wiederherstellung nicht mehr - Die vollständige Dokumentation der Endpunkte finden Sie in der API-Referenz
