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

# Envoyer des événements personnalisés avec visitors.track

> Appelez visitors.track depuis le code de votre site pour enregistrer dans Radar les inscriptions, les clics sur un bouton et les envois de formulaire, puis vérifiez que chaque événement arrive.

Un événement personnalisé est une action que vous choisissez d'enregistrer dans Radar : une inscription, un clic sur un bouton, un formulaire envoyé. Le script Radar enregistre les pages vues tout seul. Pour tout le reste, le code de votre site appelle `visitors.track` au moment où l'action a lieu. Ce guide présente l'appel, ses arguments, le bon moment pour l'envoyer et la façon de vérifier qu'il est bien arrivé.

Vous n'êtes pas développeur ? L'article du Centre d'aide sur les [événements personnalisés](https://docs.taap.it/fr/help/radar/features/custom-events.md) explique la même fonctionnalité et la lecture de son rapport, sans code.

## Avant de commencer

* **Installez le script Radar.** `visitors.track` est fourni avec le script : le script doit donc être présent sur chaque page qui envoie un événement. Consultez [installer le script](https://docs.taap.it/fr/help/radar/install-the-script.md), puis [vérifier votre installation](https://docs.taap.it/fr/help/radar/check-your-installation.md).
* **Sachez ce que le script suit déjà.** Les pages vues arrivent toutes seules, et les attributs `data-track-outbound` et `data-track-forms` de la balise activent le suivi des clics sur les liens sortants et des envois de formulaire. Consultez [le fonctionnement du script](https://docs.taap.it/fr/radar/how-the-script-works.md).
* **Vérifiez votre plan.** Les événements personnalisés sont disponibles à partir du plan Starter. Comparez les plans sur la [page des tarifs](https://taap.it/pricing).

> [!NOTE]
>
> L'objet JavaScript s'appelle `visitors`. C'est le bon nom : ne le remplacez pas par `radar` dans votre code.

## L'appel

```javascript theme={null}
visitors.track("signup", {
  plan: "pro",
  source: "footer",
});
```

| Argument | Type | Obligatoire | Ce que c'est |
| - | - | - | - |
| Nom de l'événement | chaîne de caractères | Oui | Le nom que l'événement porte dans vos rapports, par exemple `signup` ou `add_to_cart`. |
| Propriétés | objet | Non | Des détails sur cet événement précis, écrits sous forme de paires clé-valeur, par exemple `plan`, `price` ou `source`. |

Un troisième argument existe pour un seul cas : le montant d'une vente. Consultez [suivre les revenus](https://docs.taap.it/fr/radar/guides/track-revenue.md).

## Choisir les noms de vos événements

* **Gardez des noms courts et stables.** Radar regroupe les événements par nom : `signup` aujourd'hui et `sign_up` le mois prochain apparaissent donc comme deux événements différents.
* **Nommez l'action, pas la page.** `add_to_cart`, `book_call` et `newsletter_subscribe` disent ce que le visiteur a fait.
* **Réservez `payment` aux vraies ventes.** Radar traite de façon particulière un événement nommé exactement `payment` : c'est l'événement qui porte une vente et le nom de l'acheteur. Consultez [suivre les revenus](https://docs.taap.it/fr/radar/guides/track-revenue.md).

## Ajouter des propriétés

Les propriétés sont facultatives. Vous choisissez les clés et les valeurs :

```javascript theme={null}
visitors.track("add_to_cart", {
  product: "running-shoes",
  price: 89,
  source: "product_page",
});
```

Quelques clés ont un sens pour Radar : `email`, `name`, `first_name` et `last_name` décrivent le visiteur, pas l'événement. Un e-mail envoyé sur n'importe quel événement identifie le visiteur. Consultez [identifier les visiteurs](https://docs.taap.it/fr/radar/guides/identify-visitors.md).

> [!WARNING]
>
> Ne mettez un e-mail dans les propriétés que si vous voulez identifier le visiteur. Identifier des personnes a des conséquences sur le consentement. Consultez [confidentialité, cookies et RGPD](https://docs.taap.it/fr/help/radar/privacy-and-consent.md).

## Envoyer l'événement une fois l'action réussie

Appelez `visitors.track` une fois que l'action a vraiment eu lieu, pas au moment où le visiteur essaie.

Le formulaire est le piège classique. Si vous envoyez l'événement au clic sur le bouton d'envoi, vous comptez aussi toutes les tentatives qui échouent : un champ manquant, un e-mail erroné, une erreur du serveur. Votre rapport affiche alors plus d'inscriptions que vous n'en avez réellement obtenu. Attendez la réussite, puis envoyez l'événement.

| Action | Quand appeler `visitors.track` |
| - | - |
| Inscription, connexion, réservation, formulaire | Après la confirmation de l'action par votre serveur. |
| Clic sur un bouton ou un lien qui n'envoie rien à un serveur | Au clic lui-même. Le clic est l'action. |
| Achat | Après la confirmation du paiement. Consultez [suivre les revenus](https://docs.taap.it/fr/radar/guides/track-revenue.md). |

## Exemples

### Inscription

N'envoyez l'événement que lorsque le compte existe. Dans cet exemple, `createAccount` représente votre propre code d'inscription.

```javascript theme={null}
async function onSignupSubmit(event) {
  event.preventDefault();

  const result = await createAccount(new FormData(event.target));
  if (!result.success) return;

  visitors.track("signup", {
    plan: "pro",
    source: "pricing_page",
  });
}
```

### Clic sur un bouton

Un bouton qui ouvre quelque chose ou lance un téléchargement n'a ni réussite ni échec à attendre. Envoyez l'événement au clic.

```html theme={null}
<button id="download-brochure">Download the brochure</button>

<script>
  document
    .getElementById("download-brochure")
    .addEventListener("click", function () {
      visitors.track("brochure_download", {
        location: "hero",
      });
    });
</script>
```

### Formulaire

Envoyez le formulaire vous-même, vérifiez la réponse, puis envoyez l'événement. Dans cet exemple, `/api/contact` représente l'adresse à laquelle votre propre formulaire est envoyé.

```javascript theme={null}
const form = document.querySelector("#contact-form");

form.addEventListener("submit", async function (event) {
  event.preventDefault();

  const response = await fetch("/api/contact", {
    method: "POST",
    body: new FormData(form),
  });
  if (!response.ok) return;

  visitors.track("contact_form_submit", {
    form: "contact",
  });
});
```

## Protéger votre code quand le script est absent

Le script Radar se charge avec l'attribut `async` : le navigateur ne l'attend donc pas. Il peut aussi être retenu par un outil de consentement ou bloqué par une extension de navigateur. Dans ces cas, l'objet `visitors` n'existe pas, et un appel direct arrête votre code avec une erreur.

Si l'événement se trouve dans du code qui doit continuer à s'exécuter, comme une inscription ou un paiement, vérifiez d'abord que l'objet existe :

```javascript theme={null}
if (typeof visitors !== "undefined") {
  visitors.track("signup", { plan: "pro" });
}
```

## Vérifier que l'événement arrive

**1. Publier votre modification**

Testez sur votre site publié, pas sur une copie qui tourne sur votre propre ordinateur.

**2. Déclencher l'action vous-même**

Faites ce que ferait un visiteur : remplissez le formulaire, cliquez sur le bouton, terminez l'inscription.

**3. Regarder le bloc Événements personnalisés**

Ouvrez votre projet dans Radar. Sur la vue d'ensemble, le bloc Événements personnalisés affiche une ligne par nom d'événement, avec deux chiffres : **Personnes**, le nombre de visiteurs différents qui l'ont déclenché, et **Événements**, le nombre de fois où il a été déclenché.

Vous pouvez aussi lire la même liste depuis vos propres outils avec l'API Radar. Une clé API est un code secret qui permet à un programme de lire vos données. Créez-en une dans les paramètres de votre projet, sous API, et conservez-la sur votre serveur, jamais dans le code d'une page web.

```bash theme={null}
curl -X GET 'https://taap.it/api/v1/radar/custom-events?limit=20' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

Chaque entrée de la réponse contient `event_name`, `people` et `events`. Consultez l'[endpoint des événements personnalisés](https://docs.taap.it/fr/api-reference/radar/custom-events.md). L'API Radar est disponible à partir du plan Pro.

### L'événement n'apparaît pas

* **Pas de pages vues non plus.** Le problème vient de l'installation, pas de votre événement. Une clé de projet erronée (la valeur `pk_` dans le script) laisse le tableau de bord vide. Suivez [j'ai installé le script mais je ne vois aucune donnée](https://docs.taap.it/fr/help/radar/no-data.md).
* **Les pages vues arrivent, pas l'événement.** Vérifiez que votre code atteint bien la ligne `visitors.track` : un `return` prématuré, une erreur juste avant ou un objet `visitors` absent la font sauter. La console du navigateur affiche l'erreur.
* **Toujours rien.** Contactez le support depuis le chat de votre tableau de bord ou à l'adresse [hello@taap.it](mailto:hello@taap.it).

## Utiliser vos événements dans un tunnel

Un tunnel de conversion est un parcours que vous définissez étape par étape, par exemple page d'arrivée, puis formulaire envoyé, puis appel réservé. Radar montre combien de visiteurs passent de chaque étape à la suivante. Vous créez les tunnels dans le tableau de bord Radar, sans code supplémentaire : chaque étape est soit une page, soit l'un de vos événements personnalisés. Les tunnels sont disponibles à partir du plan Starter, comme les événements personnalisés.

Votre rôle de développeur est d'envoyer un événement pour chaque action qui n'a pas de page à elle :

```javascript theme={null}
visitors.track("contact_form_submit", { form: "contact" });

// Later, when the visitor books a call
visitors.track("book_call", { source: "landing" });
```

Une fois que les deux événements arrivent, ils peuvent être choisis comme étapes d'un tunnel. Consultez [créer un tunnel de conversion](https://docs.taap.it/fr/help/radar/features/funnels.md).

## Bon à savoir

* **Chaque événement compte.** Chaque événement personnalisé est décompté des événements que votre plan inclut chaque mois. Consultez [plans et événements](https://docs.taap.it/fr/help/radar/plans-and-events.md).
* **Pas de webhooks.** Radar ne prévient pas vos systèmes quand un événement se produit. Pour utiliser les événements ailleurs, lisez-les avec l'[API Radar](https://docs.taap.it/fr/api-reference/radar/introduction.md).
* **Supprimer un projet supprime ses événements.** Supprimer un projet Radar supprime toutes ses données, événements personnalisés compris.

## Étapes suivantes

> [card] [Identifier les visiteurs](https://docs.taap.it/fr/radar/guides/identify-visitors.md)
>
> Associez un e-mail ou un nom à un visiteur avec le même appel.

> [card] [Suivre les revenus](https://docs.taap.it/fr/radar/guides/track-revenue.md)
>
> Envoyez une vente à Radar depuis Stripe ou depuis votre propre page de paiement.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.