Installer Walityk sur Next.js

Ce guide couvre l’installation de Walityk dans une application Next.js, App Router (13+) ou Pages Router. Aucun package à installer : Walityk s’intègre avec un snippet et le composant next/script. Compter 10 minutes.

1. Créer votre site dans le dashboard

1. Connectez-vous au dashboard Walityk.
2. Sites → Nouveau site : renseignez votre domaine (ex. app.exemple.com) et choisissez la plateforme Custom (HTML/JS).
3. Cliquez Créer le site. L’onglet Installation de la page du site affiche votre snippet, avec votre site ID déjà renseigné.

Le domaine déclaré sert à autoriser vos requêtes (CORS) : le domaine exact et ses sous-domaines sont acceptés automatiquement. Si vous trackez plusieurs domaines distincts, créez un site par domaine.

2. Ajouter le tag — App Router

Dans app/layout.tsx, ajoutez le snippet via next/script :

import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="fr">
      <body>
        {children}
        <Script id="walityk" strategy="afterInteractive">
          {`(function(s,i,e){
  s.__tftq=s.__tftq||[];
  s.__tftq.push(['init',{site_id:i,endpoint:e+'/collect'}]);
  var t=document.createElement('script');
  t.async=true;
  t.src=e+'/tag.js';
  document.head.appendChild(t);
})(window,'VOTRE_SITE_ID','https://tag.walityk.com');`}
        </Script>
      </body>
    </html>
  );
}

Remplacez VOTRE_SITE_ID par le site ID affiché dans le dashboard (ou copiez directement le snippet généré, il est identique).

Le tag émet automatiquement dès le chargement : page_view (avec contexte complet : device, viewport, réseau, performance), jalons de scroll (25/50/75/90 %), clics sortants et form_submit. Si vous avez déjà un dataLayer GTM, ses events sont repris automatiquement.

Pages Router (alternative)

Même snippet, dans pages/_app.tsx :

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

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Script id="walityk" strategy="afterInteractive">
        {`(function(s,i,e){
  s.__tftq=s.__tftq||[];
  s.__tftq.push(['init',{site_id:i,endpoint:e+'/collect'}]);
  var t=document.createElement('script');
  t.async=true;
  t.src=e+'/tag.js';
  document.head.appendChild(t);
})(window,'VOTRE_SITE_ID','https://tag.walityk.com');`}
      </Script>
      <Component {...pageProps} />
    </>
  );
}

3. Tracker les navigations SPA

Next.js navigue côté client sans recharger la page : le tag émet le page_view initial, mais il faut lui signaler les changements de route. Créez un petit composant client :

// app/walityk-page-views.tsx
'use client';

import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect, useRef } from 'react';

export function WalitykPageViews() {
  const pathname = usePathname();
  const searchParams = useSearchParams();
  const isFirst = useRef(true);

  useEffect(() => {
    // Le tag émet lui-même le page_view initial au chargement : on ne double pas.
    if (isFirst.current) {
      isFirst.current = false;
      return;
    }
    window.__tftq = window.__tftq || [];
    window.__tftq.push(['track', 'page_view']);
  }, [pathname, searchParams]);

  return null;
}

Montez-le dans app/layout.tsx (le <Suspense> est requis par useSearchParams) :

import { Suspense } from 'react';
import { WalitykPageViews } from './walityk-page-views';

// … dans le <body> :
<Suspense fallback={null}>
  <WalitykPageViews />
</Suspense>

En Pages Router, utilisez l’event routeChangeComplete du router dans _app.tsx :

const router = useRouter();
useEffect(() => {
  const onRoute = () => {
    window.__tftq = window.__tftq || [];
    window.__tftq.push(['track', 'page_view']);
  };
  router.events.on('routeChangeComplete', onRoute);
  return () => router.events.off('routeChangeComplete', onRoute);
}, [router.events]);

TypeScript : déclarez la queue une fois dans un fichier global.d.ts : declare global { interface Window { __tftq?: unknown[][] } } export {};

4. Tracker des conversions

Poussez un event via window.__tftq.push(['track', type, propriétés]) — l’appel fonctionne que le tag soit déjà chargé ou non :

'use client';

export function SignupButton() {
  return (
    <button
      onClick={() => {
        window.__tftq = window.__tftq || [];
        window.__tftq.push(['track', 'sign_up', { plan: 'starter' }]);
      }}
    >
      Créer un compte
    </button>
  );
}

Pour un achat, sur la page de confirmation :

window.__tftq.push([
  'track',
  'purchase',
  { value: 49.0, currency: 'EUR', transaction_id: 'ORD-1234' },
]);

Les propriétés value, currency et transaction_id sont transmises telles quelles aux destinations (GA4, Meta CAPI, Google Ads…).

Types d’events standard : page_view, view_item, add_to_cart, begin_checkout, purchase, sign_up, login, lead. Tout autre nom passe en event custom.

5. Consentement

Par défaut le tag tourne en mode cookieless : aucun cookie, aucun identifiant persistant — pas de bannière nécessaire. Si vous avez une CMP (Cookiebot, Axeptio, Didomi…), passez en mode bannière en ajoutant ,mode:'banner' dans l’objet init du snippet : le tag démarre en Consent Mode v2 deny-default, détecte automatiquement la CMP et ne libère les events qu’après le choix du visiteur.

6. Vérifier

1. Dans le dashboard, ouvrez la page de votre site → Voir les events live.
2. Naviguez sur votre app (en local ou en prod) : les page_view apparaissent en temps réel.
3. Déclenchez une conversion et vérifiez qu’elle remonte, puis contrôlez GA4 Realtime si la destination est connectée.

Ça ne marche pas ?

• Aucune requête /collect dans DevTools → Network : le snippet n’est pas monté (vérifiez que le <Script> est bien dans le layout racine) ou le site_id est vide.
• Requête /collect bloquée par CORS : le domaine sur lequel tourne l’app ne correspond pas au domaine déclaré dans le dashboard. En local, testez plutôt sur le domaine de prod ou de preview déclaré.
• CSP stricte : ajoutez https://tag.walityk.com à script-src et connect-src.
• Un seul page_view par session : le composant de l’étape 3 n’est pas monté — les navigations SPA ne sont pas signalées au tag.

Et après ?

• Connectez vos destinations (GA4, Meta CAPI, Google Ads…) depuis Destinations — sans toucher au code.
• Ajoutez vos events custom au plan de marquage du site.

Besoin d’aide ? hi@walityk.com.