Installer Walityk sur Next.js

Ce guide couvre l’installation de Walityk dans une application Next.js, App Router (15+) ou Pages Router (12+). Compter 15 minutes.

1. Installer le SDK

pnpm add @walityk/next
# ou npm install @walityk/next / yarn add @walityk/next

2. Configurer la clé de site

Récupérez votre clé depuis le dashboard Walityk (Sites → Nouveau site → Next.js), puis ajoutez-la à .env.local :

NEXT_PUBLIC_WALITYK_SITE_KEY=wlk_live_xxxxxxxxxxxxx
WALITYK_SERVER_KEY=wlk_srv_xxxxxxxxxxxxx

La SITE_KEY est publique (utilisée côté client pour les page_view). La SERVER_KEY est secrète : elle signe les events server-side et ne doit jamais être exposée.

3. App Router — provider racine

Dans app/layout.tsx :

import { WalitykProvider } from '@walityk/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <WalitykProvider siteKey={process.env.NEXT_PUBLIC_WALITYK_SITE_KEY!}>
          {children}
        </WalitykProvider>
      </body>
    </html>
  );
}

Les page_view sont envoyés automatiquement à chaque navigation (router events).

Pages Router (alternative)

Dans pages/_app.tsx :

import { WalitykProvider } from '@walityk/next';

export default function App({ Component, pageProps }) {
  return (
    <WalitykProvider siteKey={process.env.NEXT_PUBLIC_WALITYK_SITE_KEY!}>
      <Component {...pageProps} />
    </WalitykProvider>
  );
}

4. Tracker un event client

'use client';
import { useWalityk } from '@walityk/next';

export function SignupButton() {
  const { track } = useWalityk();
  return (
    <button onClick={() => track('signup_clicked', { plan: 'starter' })}>
      Sign up
    </button>
  );
}

5. Tracker un event server-side

Pour les conversions critiques (purchase, signup confirmé), envoyez l’event depuis votre Route Handler ou Server Action :

// app/api/checkout/route.ts
import { walityk } from '@walityk/next/server';

export async function POST(req: Request) {
  const { orderId, amount, email } = await req.json();
  await walityk.track('purchase', {
    value: amount,
    currency: 'EUR',
    transaction_id: orderId,
    user: { email },
  }, { request: req });
  return Response.json({ ok: true });
}

Le SDK server lit WALITYK_SERVER_KEY automatiquement depuis process.env. Il hash automatiquement les PII (email, phone) avant envoi.

6. Vérifier

Ouvrez le Live debug dans le dashboard Walityk, naviguez sur votre app local et déclenchez une conversion. Les events apparaissent en temps réel.

Bonnes pratiques

✅ Server-side d’abord pour les conversions monétaires (purchase, subscribe).
✅ Client-side uniquement pour le comportement (clic, scroll, page_view).
✅ Utilisez headers() côté server pour récupérer le cookie _wlk qui assure le link client/server.
❌ Ne loggez jamais la SERVER_KEY côté client (NEXT_PUBLIC_* est public !).

Et après ?

Connectez vos destinations (GA4, Meta, Google Ads) depuis le dashboard.
Lisez la doc Edge runtime si vous déployez sur Vercel Edge ou Cloudflare Workers.

Besoin d’aide ? hi@walityk.com.