React (Vite)

Installez le snippet de suivi Selgeo dans une application React monopage construite avec Vite. La voie recommandée est une balise <script> simple dans index.html — la même ligne unique que le tableau de bord affiche. Une alternative par injection useEffect est documentée en fin de page pour les projets qui ne peuvent pas modifier index.html.

Version API : v1

Si vous n'utilisez pas Vite + React, consultez plutôt le guide HTML / script simple, le guide Next.js ou le guide WordPress.

Pourquoi `index.html` ?

Dans une SPA Vite, index.html est le point d'entrée canonique : il est livré au navigateur avant l'exécution de tout code React, chaque route est servie depuis le même fichier, et le navigateur gère automatiquement la déduplication des balises <script>. Placer le snippet ici signifie :

Le snippet est disponible avant l'hydratation de React, donc un ?ref=… initial est capturé même en cache froid.
Pas de useEffect, pas de risque de double montage, pas de surprises avec React Strict Mode.
Une source unique de vérité — pas besoin de se rappeler d'injecter le snippet dans chaque composant de layout.

Comme le snippet est sans cookie et basé sur sessionStorage, il est sûr de le charger sur chaque page d'une SPA Vite sans changer le comportement de votre application React.

Installation — Voie recommandée

Étape 1 : Ouvrez `index.html`

Les projets Vite conservent index.html à la racine du projet (à côté de vite.config.ts), pas dans public/. Ouvrez-le dans votre éditeur.

Étape 2 : Ajoutez le snippet avant le module de l'application

Placez le <script> Selgeo avant <script type="module" src="/src/main.tsx"></script> afin que la requête async du snippet soit déjà en vol avant que le module de l'application React ne commence à être évalué. C'est ce qui permet à Selgeo de voir le ?ref=… initial dès le premier paint, avant que React, le routeur ou toute réécriture côté client ne touchent à l'URL.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Your App</title>
  </head>
  <body>
    <div id="root"></div>

    <script
      async
      src="https://cdn.selgeo.com/v1/selgeo.js"
      data-merchant="pk_test_YOUR_KEY"
    ></script>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Remplacez pk_test_YOUR_KEY par votre clé d'API publique depuis Paramètres > Clés API dans le tableau de bord Selgeo.

index.html ouvert dans l'éditeur avec la balise script Selgeo ajoutée au-dessus du script du module de l'application

Étape 3 : Redémarrer le serveur de développement

pnpm dev
# ou
npm run dev

Vite prend en compte les modifications de index.html au démarrage à froid. Le rechargement à chaud des modules manque parfois les éditions HTML, donc un redémarrage est l'option la plus sûre.

Attributs requis et optionnels

Attribut	Requis	Description
`src`	Oui	URL du CDN. Toujours `https://cdn.selgeo.com/v1/selgeo.js`.
`data-merchant`	Oui	Votre clé d'API publique (`pk_test_` ou `pk_live_`).
`async`	Oui	Chargement asynchrone ; ne bloque pas l'hydratation de React.
`data-debug`	Non	Journalisation verbose dans la console. À supprimer avant la mise en production.
`data-api-url`	Non	Surcharge le point de terminaison API. Présent uniquement dans les espaces de travail staging / dev — le tableau de bord Selgeo l'injecte automatiquement au besoin.

Le snippet écoute les événements popstate, history.pushState et history.replaceState. Si vous utilisez TanStack Router, React Router ou tout autre routeur côté client, aucune configuration supplémentaire n'est nécessaire — un paramètre ?ref=… introduit sur n'importe quelle route est capturé automatiquement.

Vérification de l'installation

Démarrez le serveur de développement (pnpm dev).
Créez un lien de suivi dans le tableau de bord Selgeo sous Programmes > Liens de suivi.
Ouvrez le lien de suivi dans un nouvel onglet du navigateur :
```
http://localhost:5173/?ref=VOTRE_REF_DE_TEST
```
Ouvrez les Outils de développement (F12) et vérifiez la Console. Avec data-debug ajouté temporairement, vous verrez :
```
[selgeo] ref detected VOTRE_REF_DE_TEST
[selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
Exécutez dans la console :
```
__selgeo.getClickId()
```
Ceci devrait retourner une chaîne UUID.
Ouvrez le tableau de bord Selgeo. Le clic devrait apparaître dans Analytics en quelques secondes.

Console DevTools du navigateur affichant les lignes de débogage selgeo ref detected et selgeo click_id stored

Alternative : injection par `useEffect`

Utilisez cette voie uniquement si vous ne pouvez pas modifier index.html — par exemple, si votre index.html est généré par un framework de niveau supérieur, ou si vous intégrez le snippet dans un micro-frontend dont vous ne possédez pas la couche HTML.

Ce motif comporte une préoccupation supplémentaire : en React 18+ Strict Mode (par défaut dans les templates Vite), les effets s'exécutent deux fois en développement. Sans garde-fou, le snippet serait injecté deux fois et un clic dupliqué pourrait être enregistré. Utilisez un id stable d'élément plus un court-circuit document.getElementById :

// src/components/SelgeoSnippet.tsx
import { useEffect } from 'react';

const SELGEO_SCRIPT_ID = 'selgeo-snippet';

export function SelgeoSnippet() {
  useEffect(() => {
    if (document.getElementById(SELGEO_SCRIPT_ID)) {
      return;
    }

    const script = document.createElement('script');
    script.id = SELGEO_SCRIPT_ID;
    script.async = true;
    script.src = 'https://cdn.selgeo.com/v1/selgeo.js';
    script.setAttribute('data-merchant', 'pk_test_YOUR_KEY');
    document.body.appendChild(script);
  }, []);

  return null;
}

Montez <SelgeoSnippet /> une seule fois près de la racine de votre arbre de composants (généralement dans App.tsx, à côté de votre provider de routeur).

Pourquoi le garde-fou est important :

React 18+ Strict Mode invoque intentionnellement les effets deux fois en développement pour faire ressortir les bogues d'effets de bord.
Sans le court-circuit document.getElementById, deux éléments <script> seraient ajoutés, les deux s'exécuteraient, et le snippet enregistrerait deux clics pour le même visiteur.
L'id="selgeo-snippet" stable permet au garde-fou de fonctionner à travers les rechargements à chaud, les changements de route et les remontages de composants.

Ce motif est aussi utile quand la gestion du consentement ou les feature flags doivent conditionner le chargement du snippet — enveloppez le corps de l'effet dans votre condition.

Dépannage

Le snippet ne se charge pas

Confirmez que le <script> est à l'intérieur de <body>, pas dans <head> (le index.html de Vite devrait déjà avoir un <body>).
Exécutez pnpm build et inspectez dist/index.html. Le snippet doit apparaître dans le HTML compilé.
Si vous utilisez un plugin Vite personnalisé qui réécrit index.html, assurez-vous qu'il préserve les balises <script> ajoutées par l'utilisateur.
Vérifiez dans l'onglet Network du navigateur la requête selgeo.js — une erreur CORS ou CSP indique un problème de configuration (voir ci-dessous).

Le clic n'est pas suivi

Le visiteur doit arriver avec ?ref=… sur le chargement initial de la page. Les rechargements suppriment le paramètre (le snippet réécrit l'URL à la capture) — émettez un lien de suivi neuf si vous avez déjà consommé l'actuel.
Vérifiez que data-merchant contient une clé pk_test_* ou pk_live_* valide.
Si vous utilisez l'alternative useEffect, confirmez que le garde-fou document.getElementById est en place et que SELGEO_SCRIPT_ID est unique sur la page.
Vérifiez le mode du tableau de bord (test vs. live) — un décalage écarte le clic silencieusement.

Blocage CSP

Si vous définissez une Content-Security-Policy via un plugin Vite, une balise meta ou le serveur d'origine, autorisez les origines Selgeo :

script-src 'self' https://cdn.selgeo.com;
connect-src 'self' https://api.selgeo.com;

Pour les espaces de travail staging / dev où data-api-url pointe ailleurs, ajoutez également cette origine à connect-src.

Étapes suivantes

Stripe Payment Links — intégration Stripe sans backend.
Stripe Checkout — passez click_id aux Checkout Sessions depuis votre serveur.
Conversion API — suivez les conversions non-Stripe.
Configuration du snippet — référence complète des attributs et la balise HTML sous-jacente.

Pourquoi index.html ?​

Installation — Voie recommandée​

Étape 1 : Ouvrez index.html​

Étape 2 : Ajoutez le snippet avant le module de l'application​

Étape 3 : Redémarrer le serveur de développement​

Attributs requis et optionnels​

Navigation monopage​

Vérification de l'installation​

Alternative : injection par useEffect​

Dépannage​

Le snippet ne se charge pas​

Le clic n'est pas suivi​

Blocage CSP​

Étapes suivantes​