Vue d’ensemble
Les événements personnalisés enregistrent des actions d’utilisateurs venues de systèmes externes (e-commerce, CRM, outils d’analyse). Ils apparaissent dans la chronologie du contact, et leurs objectifs permettent de créer des segments RFM (récence, fréquence, montant).
Chronologie du contact
Chaque événement personnalisé crée une entrée dans la chronologie du contact, ce qui vous donne l’historique complet de ses interactions :
Chaque événement affiche son event_name comme type d’entrée dans la chronologie (par exemple « order.completed », « subscription.started »). Le champ properties contient un contexte supplémentaire, visible dans le détail de l’entrée.
Types d’objectifs
Les segments s’appuient sur les objectifs. Chaque événement peut suivre un objectif :
| Type | Cas d’usage | goal_value |
|---|---|---|
purchase | Commandes e-commerce, paiements ponctuels | Requis |
subscription | Abonnements SaaS, adhésions | Requis |
lead | Formulaires de contact, demandes de démo | Facultatif |
signup | Créations de compte | Facultatif |
booking | Rendez-vous, consultations | Facultatif |
trial | Activations d’essai gratuit | Facultatif |
other | Événements de conversion personnalisés | Facultatif |
Créer des segments RFM
L’analyse RFM (récence, fréquence, montant) repère vos meilleurs clients. Utilisez l’éditeur de segments avec des conditions Objectif :
Montant : dépense totale
Choisissez le type d’objectif Achat et l’agrégat total, puis fixez une valeur minimale pour trouver les clients qui dépensent le plus.
Fréquence : nombre d’achats
Choisissez le type d’objectif Achat et l’agrégat nombre, puis fixez un minimum pour trouver les clients qui achètent régulièrement.
Récence : activité récente
Utilisez le filtre de période « dans les X derniers jours » pour trouver les clients qui ont acheté récemment.
Exemples de segments RFM
- Clients VIP : plus de 1000 $ dépensés ET au moins 5 commandes ET un achat dans les 60 derniers jours
- Gros clients à risque : plus de 500 $ dépensés ET aucun achat depuis 90 jours
- Nouveaux clients à fort potentiel : premier achat de plus de 200 $ dans les 30 derniers jours
Options d’agrégat
| Option | Description |
|---|---|
| Total | Somme de toutes les valeurs d’objectif (dépense sur toute la durée de vie) |
| Nombre | Nombre d’événements (nombre de commandes) |
| Moyenne | Valeur moyenne de l’objectif (panier moyen) |
| Minimum | Plus petite valeur d’objectif |
| Maximum | Plus grande valeur d’objectif |
Options de période
| Option | Description |
|---|---|
| N’importe quand | Tout l’historique |
| Dans les X derniers jours | Fenêtre glissante |
| Dans la plage de dates | Période précise |
| Avant la date | Limite dans le passé |
| Après la date | Depuis une date précise |
Suivre des événements
Événement unique
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
}'
Import par lot
Importez jusqu’à 50 événements à la fois :
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 des noms d’événements
Les noms d’événements s’écrivent en minuscules, avec des lettres, des chiffres, des points, des tirets bas, des traits d’union ou des barres obliques :
order.completedsubscription/startedform_submituser-signup
Note
Les objectifs enregistrés par l’analyse web arrivent dans la chronologie du contact selon une règle plus stricte : uniquement des lettres ASCII, des chiffres, des points et des barres obliques. Tout autre caractère, traits d’union et caractères accentués compris, est remplacé par un tiret bas. Un objectif web nommé user-signup arrive sous la forme user_signup. Si vous envoyez le même événement par les deux chemins, choisissez un nom qui passe dans les deux cas.
Gérer les remboursements
Utilisez une goal_value négative pour les remboursements, afin que les calculs de LTV restent justes :
{
"email": "customer@example.com",
"event_name": "order.refunded",
"external_id": "refund_12345",
"goal_type": "purchase",
"goal_value": -50.00
}
Permissions
Les événements personnalisés n’ont pas de permission propre : ils relèvent de Contacts. Enregistrer ou importer un événement demande Contacts en écriture, et en lire un demande Contacts en lecture. Accorder Contacts en lecture donne donc aussi accès aux événements enregistrés sur vos contacts, et à la chronologie qu’ils alimentent. Voir Admins et clés API.
Remarques
customEvents.upsertcrée le contact quand aucun contact n’a cet email.customEvents.importne crée aucun contact- Un événement n’est mis à jour que si son
occurred_atest plus récent que celui de l’événement existant - Suppression logique en renseignant
deleted_at(le remettre ànullrestaure l’événement) - Seul un nouvel événement (un nouvel
external_id) lance les automations déclenchées par son nom ; depuis la 44.0, une mise à jour, une suppression logique ou une restauration ne le fait pas - Voir la référence de l’API pour la documentation complète de l’endpoint
