Intégration Next.js

Ce guide détaille l’intégration sur Next.js App Router, avec le suivi automatique des pageviews SPA et une astuce de proxy pour éviter les problèmes CORS en développement.

1. Provider au root layout

app/layout.tsx

import { AnalyticsProvider } from "@jichio/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="fr">
      <body>
        <AnalyticsProvider
          apiKey={process.env.NEXT_PUBLIC_ANALYTICS_KEY!}
          endpoint={process.env.NEXT_PUBLIC_ANALYTICS_ENDPOINT!}
        >
          {children}
        </AnalyticsProvider>
      </body>
    </html>
  );
}

Le provider gère l’instance, les pageviews SPA (usePathname) et délègue l’auto-capture (pageview initial + clics) au core.

2. Variables d’environnement

.env.local

NEXT_PUBLIC_ANALYTICS_KEY=<votre-clé-projet>
NEXT_PUBLIC_ANALYTICS_ENDPOINT=/jichio

En développement, pointer l’endpoint vers un chemin same-origin (/jichio) et proxifier vers l’API évite le preflight CORS. Voir §3.

3. Proxy same-origin (dev)

Un appel cross-origin (http://localhost:3000 → http://localhost:8000) déclenche un preflight OPTIONS qui, si l’API locale ne le gère pas, bloque le POST. La parade en dev : proxifier /jichio vers l’API d’ingestion.

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: "/jichio/:path*",
        destination: "http://localhost:8000/:path*",
      },
    ];
  },
};

export default nextConfig;

Avec NEXT_PUBLIC_ANALYTICS_ENDPOINT=/jichio, le SDK enverra vers /jichio/v1/events (same-origin), proxifié vers http://localhost:8000/v1/events.

Navigateur → http://localhost:3000/jichio/v1/events
          → proxy → http://localhost:8000/v1/events

4. En production

Deux options :

Même origine / reverse-proxy : servez l’API sous le même domaine que le front (pas de CORS).
Appel direct : configurez le CORS côté API d’ingestion. Voir Dépannage.

5. Pageviews SPA

Aucune action requise : l’adaptateur écoute les changements de route App Router et émet analytics.page({ loadType: "spa-navigation" }) automatiquement. Le premier chargement porte loadType: "initial" (auto-capture core).

Pour tracker un événement lié à une navigation métier précise (et non un simple pageview), utilisez track() dans le composant concerné.

Prise en main

SDK

Concepts

Guides

Intégration Next.js

1. Provider au root layout

2. Variables d’environnement

3. Proxy same-origin (dev)

4. En production

5. Pageviews SPA

​1. Provider au root layout

​2. Variables d’environnement

​3. Proxy same-origin (dev)

​4. En production

​5. Pageviews SPA

1. Provider au root layout

2. Variables d’environnement

3. Proxy same-origin (dev)

4. En production

5. Pageviews SPA