> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Événements personnalisés et objectifs

> Suivez le comportement des utilisateurs et leurs objectifs de conversion pour créer des segments RFM et enrichir la chronologie des contacts.

## 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 :

![Chronologie d'un contact avec des événements personnalisés](https://www.notifuse.com/docs/assets/screenshots/custom_event_timeline.png)

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** :

![Éditeur de segments avec un objectif d'événements personnalisés](https://www.notifuse.com/docs/assets/screenshots/segment_goals.png)

### 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

```bash
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 :

```bash
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.completed`
- `subscription/started`
- `form_submit`
- `user-signup`

> [!NOTE]
>
> Les objectifs enregistrés par l'[analyse web](https://www.notifuse.com/fr/docs/web-analytics/goals.md) 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 :

```json
{
  "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](https://www.notifuse.com/fr/docs/features/admins-api-keys.md).

## Remarques

- `customEvents.upsert` crée le contact quand aucun contact n'a cet email. `customEvents.import` ne crée aucun contact
- Un événement n'est mis à jour que si son `occurred_at` est plus récent que celui de l'événement existant
- Suppression logique en renseignant `deleted_at` (le remettre à `null` restaure 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](https://www.notifuse.com/docs/api-reference/import-custom-events.md) pour la documentation complète de l'endpoint
