Aller au contenu principal

Next.js

Installez le snippet de suivi Selgeo dans une application Next.js avec le composant natif next/script du framework. Ce guide couvre à la fois l'App Router (app/layout.tsx) et le Pages Router (pages/_app.tsx).

Version API : v1

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

Pourquoi next/script ?​

Une balise <script> simple dans un composant React ne se comporte pas comme en HTML brut — Next.js empaquette le JavaScript par route et hydrate les pages de manière incrémentale. Le composant officiel next/script :

  • Charge le snippet exactement une fois lors des navigations côté client (pas d'exécution dupliquée).
  • Respecte une strategy de chargement que vous contrôlez (nous utilisons afterInteractive).
  • Fonctionne bien avec le SSR en streaming de Next.js et le Partial Prerendering.

Nous utilisons strategy="afterInteractive" plutôt que lazyOnload afin que le snippet soit prêt avant le traitement du premier paramètre ?ref=. La précision de l'attribution prime sur un gain marginal de score Lighthouse — lazyOnload risque de manquer un clic précoce qui convertit immédiatement.

Installation — App Router (app/layout.tsx)​

Pour les projets sur Next.js 13+ utilisant le répertoire app/.

Étape 1 : Ajouter le snippet au layout racine​

Ouvrez app/layout.tsx et ajoutez l'import Script et l'élément JSX :

import Script from 'next/script';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          async
          src="https://cdn.selgeo.com/v1/selgeo.js"
          data-merchant="pk_test_YOUR_KEY"
          strategy="afterInteractive"
        />
      </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.

Page Settings &gt; API Keys du tableau de bord Selgeo avec le champ de la clé publique mis en évidence

Étape 2 : Sauvegarder et lancer​

pnpm dev
# ou
npm run dev

Ouvrez votre site dans le navigateur. Le snippet se charge maintenant sur chaque page rendue par l'App Router.

Installation — Pages Router (pages/_app.tsx)​

Pour les projets sur l'ancien répertoire pages/.

Étape 1 : Ajouter le snippet au composant App personnalisé​

Ouvrez (ou créez) pages/_app.tsx :

import type { AppProps } from 'next/app';
import Script from 'next/script';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        async
        src="https://cdn.selgeo.com/v1/selgeo.js"
        data-merchant="pk_test_YOUR_KEY"
        strategy="afterInteractive"
      />
    </>
  );
}

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

pnpm dev

Les projets Pages Router doivent redémarrer le serveur de développement lors de la première création de _app.tsx. Les éditions ultérieures se rechargent à chaud normalement.

Carte Tracking Snippet dans Settings affichant l&#39;onglet Next.js avec les blocs d&#39;import et de composant prêts à copier

Attributs requis et optionnels​

AttributRequisDescription
srcOuiURL du CDN. Toujours https://cdn.selgeo.com/v1/selgeo.js.
data-merchantOuiVotre clé d'API publique (pk_test_* ou pk_live_*).
asyncOuiChargement asynchrone ; ne bloque pas l'hydratation.
strategyOuiUtilisez "afterInteractive". Ne basculez pas vers "lazyOnload" — des clics précoces de parrainage pourraient être manqués.
data-debugNonActive la journalisation verbose dans la console. À supprimer avant la mise en production.
data-api-urlNonSurcharge 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.

Vérification de l'installation​

  1. Compilez et lancez votre projet (pnpm dev ou pnpm build && pnpm start).
  2. Créez un lien de suivi dans le tableau de bord Selgeo sous Programmes > Liens de suivi.
  3. Visitez votre site avec le lien de suivi, par exemple : 
    https://votre-site.com/?ref=VOTRE_REF_DE_TEST
  4. Ouvrez les Outils de développement (F12) et vérifiez la Console. Avec data-debug ajouté temporairement, vous devriez voir : 
    [selgeo] ref detected VOTRE_REF_DE_TEST
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. Dans la console du navigateur, exécutez : 
    __selgeo.getClickId()
    Ceci devrait retourner une chaîne UUID. null signifie que le snippet n'a pas détecté de paramètre ?ref=.
  6. Ouvrez le tableau de bord Selgeo. Le clic devrait apparaître dans Analytics en quelques secondes.

Vue Analytics de Selgeo affichant l&#39;activité récente des clics et les meilleurs partenaires

Dépannage​

Le snippet ne se charge pas​

  • Confirmez que app/layout.tsx (App Router) ou pages/_app.tsx (Pages Router) contient bien le bloc <Script> — la duplication accidentelle dans un seul fichier de page est l'erreur la plus courante.
  • Vérifiez que src est exactement https://cdn.selgeo.com/v1/selgeo.js. Une faute de frappe entraîne un échec silencieux du chargement du script.
  • Ouvrez l'onglet Network et filtrez par selgeo.js. Une entrée rouge avec statut 0 ou une erreur CORS indique généralement une violation CSP — voir ci-dessous.
  • Si vous fonctionnez en export statique (output: 'export'), vérifiez que le snippet est inclus dans le HTML exporté. next/script avec strategy="afterInteractive" est préservé par l'export statique.

Le clic n'est pas suivi​

  • Le visiteur doit arriver avec ?ref=… sur le chargement initial de la page. Une fois que le snippet capture le clic, l'URL est réécrite et le paramètre n'apparaît plus. Rechargez la page avec 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. Une valeur tronquée ou commençant par un espace fait que le snippet ne fait rien silencieusement.
  • Si vous utilisez React Strict Mode, assurez-vous que le snippet est dans app/layout.tsx ou pages/_app.tsx, et non dans un effet qui peut s'exécuter deux fois. next/script dédoublonne déjà correctement.
  • Vérifiez le mode du tableau de bord Selgeo (test vs. live). Une clé pk_live_* sur un lien de suivi émis en mode test n'enregistre pas le clic.

Blocage CSP​

Si votre projet Next.js définit une en-tête Content-Security-Policy (via next.config.js headers(), un middleware ou une entrée vercel.json), 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. Si vous ne pouvez pas assouplir la CSP, envisagez d'acheminer le snippet via votre propre origine (avancé, hors du périmètre de ce guide).

Étapes suivantes​