Aller au contenu principal

Configuration du snippet

Cette page est le guide d'installation HTML / script simple pour le snippet de suivi Selgeo (selgeo.js) — un fichier JavaScript léger qui s'exécute sur votre site web, enregistre les clics de parrainage des partenaires et stocke les données d'attribution dans le navigateur du visiteur pour une correspondance de conversion ultérieure. Utilisez ce guide si vous contrôlez directement le HTML brut de votre site (sites statiques, Webflow, Shopify Liquid, pages personnalisées rendues côté serveur ou un gestionnaire de balises).

Vous utilisez un framework ?
  • Next.js — consultez le guide Next.js pour le motif du composant next/script.
  • React (Vite) — consultez le guide React (Vite) pour le placement dans index.html et le repli useEffect.
  • WordPress — consultez le guide WordPress pour le placement via Éditeur du site, footer.php et plugins d'en-tête / pied de page.

Version API : v1

Installation de base​

Ajoutez la balise <script> suivante à chaque page de votre site web, juste avant la balise </body> fermante :

<script
  async
  src="https://cdn.selgeo.com/v1/selgeo.js"
  data-merchant="pk_test_YOUR_KEY"
></script>

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

Attributs requis​

AttributDescription
srcURL CDN du snippet. Utilisez toujours https://cdn.selgeo.com/v1/selgeo.js.
data-merchantVotre clé API publique (pk_test_* pour le mode test, pk_live_* pour le mode live).
asyncCharge le snippet de manière asynchrone pour ne pas bloquer le rendu de la page.

Attributs optionnels​

AttributDescription
data-debugActive la journalisation de débogage dans la console du navigateur. Supprimer avant de passer en production.
data-api-urlRemplace l'URL du point de terminaison API. Pour utilisation avancée uniquement (ex. proxy personnalisé).

Fonctionnement​

Lorsqu'un visiteur arrive sur votre site avec un paramètre ?ref= dans l'URL (ex. https://votre-site.com/pricing?ref=abc123), le snippet :

  1. Détecte le paramètre de requête ref.
  2. Enregistre le clic auprès de l'API Selgeo en utilisant votre clé publique.
  3. Stocke le click_id retourné par l'API dans le sessionStorage du navigateur.
  4. Supprime ?ref= de l'URL en utilisant history.replaceState pour garder les URLs propres.
  5. Réécrit les Liens de paiement Stripe sur la page pour inclure client_reference_id=CLICK_ID.

S'il n'y a pas de paramètre ?ref=, le snippet ne fait rien. Il a un overhead nul sur les pages où aucun parrainage n'a lieu.

Mécanisme de stockage​

Le snippet stocke les données d'attribution dans sessionStorage, pas dans des cookies :

CléValeurDurée de vie
__selgeo_cidLe click_id (UUID)Jusqu'à la fermeture de l'onglet du navigateur
__selgeo_vtkUn jeton de visiteur (UUID)Jusqu'à la fermeture de l'onglet du navigateur

Implications pour la confidentialité :

  • sessionStorage est limité à l'onglet — il n'est pas partagé entre les onglets ou les fenêtres.
  • Les données sont automatiquement effacées lorsque l'onglet est fermé.
  • Aucun cookie n'est défini. Aucune bannière de consentement aux cookies n'est requise pour le suivi Selgeo.
  • Le snippet n'envoie aucune donnée à Selgeo sauf si un paramètre ?ref= est présent.

Lecture de l'ID de clic​

Votre code frontend peut lire le click_id stocké à tout moment :

const clickId = __selgeo.getClickId();
// Retourne une chaîne UUID (ex. "f47ac10b-58cc-4372-a567-0e02b2c3d479")
// Retourne null si aucun clic de parrainage n'a été enregistré dans cette session

C'est utile lorsque vous devez passer le click_id à votre backend — par exemple, lors de la création d'une Session de paiement Stripe ou de l'appel à l'API de conversion.

Méthodes disponibles​

MéthodeRetourneDescription
__selgeo.getClickId()string | nullL'ID de clic actuel, ou null si aucun n'existe
__selgeo.getVisitorToken()string | nullLe jeton de visiteur actuel, ou null
__selgeo.checkUrl()voidVérifie manuellement l'URL actuelle pour un paramètre ?ref=

Applications monopage (SPAs)​

Le snippet surveille automatiquement les changements d'URL dans les applications monopage. Il écoute :

  • Les événements popstate (navigation avant/arrière du navigateur)
  • Les appels history.pushState et history.replaceState (navigation programmatique)

Lorsque l'URL change et contient un nouveau paramètre ?ref=, le snippet capture le clic automatiquement. Aucune configuration supplémentaire n'est nécessaire pour React, Vue, Angular ou d'autres frameworks SPA.

Vérification manuelle de l'URL​

Dans les rares cas où la détection automatique ne se déclenche pas (ex. le paramètre ?ref= est ajouté après le chargement de la page via JavaScript sans utiliser history.pushState), vous pouvez demander manuellement au snippet de revérifier :

__selgeo.checkUrl();

Réécriture automatique des Liens de paiement Stripe​

Si votre page contient des liens vers des Liens de paiement Stripe (https://buy.stripe.com/...), le snippet ajoute automatiquement ?client_reference_id=CLICK_ID lorsqu'un clic de parrainage est actif.

<!-- Avant l'exécution du snippet -->
<a href="https://buy.stripe.com/test_abc123">S'abonner</a>

<!-- Après l'exécution du snippet (quand un click_id est stocké) -->
<a href="https://buy.stripe.com/test_abc123?client_reference_id=CLICK_ID">S'abonner</a>

Le snippet surveille également les Liens de paiement ajoutés dynamiquement (via MutationObserver) et les réécrit au fur et à mesure qu'ils apparaissent. Cela fonctionne avec les SPAs et le contenu chargé en différé.

Protection contre la surcharge marchand : Si vous définissez vous-même client_reference_id sur un Lien de paiement, le snippet ne remplacera pas votre valeur. Votre valeur explicite a toujours la priorité.

Pour un guide détaillé, voir Liens de paiement Stripe.

Installation via gestionnaire de balises​

Si vous utilisez Google Tag Manager (GTM) ou un autre gestionnaire de balises, ajoutez le snippet comme balise HTML personnalisée :

  1. Créez une nouvelle balise HTML personnalisé dans GTM.
  2. Collez la balise script : 
    <script
      async
      src="https://cdn.selgeo.com/v1/selgeo.js"
      data-merchant="pk_test_YOUR_KEY"
    ></script>
  3. Définissez le déclencheur sur Toutes les pages.
  4. Publiez le conteneur.
Timing du gestionnaire de balises

Lors de l'utilisation d'un gestionnaire de balises, le snippet peut se charger légèrement plus tard qu'une balise <script> directe. C'est acceptable pour la plupart des cas d'usage, mais si vous avez besoin du click_id immédiatement au chargement de la page (ex. pour le passer à un formulaire de paiement rendu côté serveur), ajoutez le snippet directement à votre HTML.

Recommandations de placement​

ScénarioRecommandation
Site web standardAjouter à chaque page via le layout/template global
SPA (React, Vue, etc.)Ajouter une fois à index.html — le snippet gère les changements de route
Pages d'atterrissage uniquementAjouter uniquement aux pages où le trafic partenaire atterrit
Page de paiement uniquementNon recommandé — le snippet doit être sur la page d'atterrissage pour capturer le paramètre ?ref=
Le snippet doit être sur la page d'atterrissage

Le paramètre ?ref= n'est présent que dans l'URL initiale lorsque le visiteur clique sur un lien partenaire. Si le snippet n'est pas chargé sur cette page, le clic ne sera pas enregistré et le click_id ne sera pas disponible pour l'attribution de conversion ultérieure.

Vérifier votre installation​

  1. Ajoutez data-debug à la balise script temporairement.
  2. Visitez votre site avec un lien de suivi de test : https://votre-site.com/?ref=VOTRE_REF_TEST
  3. Ouvrez les Outils de développement (F12) et vérifiez la Console pour : 
    [selgeo] ref detected VOTRE_REF_TEST
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  4. Vérifiez sessionStorage dans l'onglet Application (Chrome) ou Stockage (Firefox) :
    • __selgeo_cid doit contenir un UUID
    • __selgeo_vtk doit contenir un UUID
  5. Appelez l'API dans la console : 
    __selgeo.getClickId()  // Doit retourner une chaîne UUID
  6. Vérifiez le tableau de bord — le clic doit apparaître dans Analytics en quelques secondes.

Dépannage​

Le snippet ne se charge pas​

  • Vérifiez que l'URL src est exactement https://cdn.selgeo.com/v1/selgeo.js.
  • Vérifiez les en-têtes Content Security Policy (CSP) qui pourraient bloquer le script. Ajoutez cdn.selgeo.com à votre directive script-src.
  • Vérifiez les bloqueurs de publicités qui pourraient bloquer le script.

click_id est null​

  • Le visiteur doit arriver avec un paramètre ?ref= dans l'URL. Les visites directes ne créent pas de click_id.
  • Vérifiez que data-merchant contient une clé publique valide (pk_test_* ou pk_live_*).
  • Vérifiez que la valeur ref correspond à un lien de suivi actif dans votre programme.

Les Liens de paiement Stripe ne sont pas réécrits​

  • Le href du lien doit commencer par https://buy.stripe.com. Les URLs relatives ou proxiées ne sont pas détectées.
  • La réécriture ne se produit que lorsqu'un click_id est stocké. Visitez d'abord la page via un lien de suivi.
  • Si vous définissez vous-même client_reference_id, le snippet ne le remplacera pas.

Performance​

Le snippet est conçu pour avoir un impact minimal sur votre site :

MétriqueValeur
Taille du bundle< 5 Ko gzippé
Temps d'initialisation< 50 ms
Requêtes réseau0 (pas de parrainage) ou 1 (enregistrement du clic de parrainage)
Cookies définisAucun
Modifications DOMAucune (sauf nettoyage de l'URL via history.replaceState)

Le snippet s'exécute entièrement dans un IIFE (Immediately Invoked Function Expression) et ne pollue pas la portée globale au-delà de l'objet API __selgeo.

Prochaines étapes​