Installer sur Next.js

Prérequis

Next.js avec l’App Router, React 18 ou 19.
Une clé d’ingestion (Concepts clés).

1. Installer le package

pnpm add @jichio/react

@jichio/core est installé avec lui.

2. Déclarer la clé

.env.local

NEXT_PUBLIC_ANALYTICS_KEY=jch_sb_xxxxxxxxxxxxxxxx

Le préfixe NEXT_PUBLIC_ est obligatoire : la clé est lue dans le navigateur. Elle n’est pas secrète (elle ne permet que l’envoi d’événements). Utilisez une clé différente par environnement de déploiement : Bac à sable en local, Production en production. Voir Environnements.

3. Monter le provider

Placez AnalyticsProvider dans le root layout, autour de children :

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!}>
          {children}
        </AnalyticsProvider>
      </body>
    </html>
  );
}

AnalyticsProvider est déjà un composant client : vous pouvez l’importer depuis un layout serveur sans ajouter "use client".

4. Redémarrer le serveur

Next.js intègre les variables NEXT_PUBLIC_* au démarrage. Après avoir modifié .env.local, relancez pnpm dev.

Ce qui est suivi automatiquement

La première page au chargement, puis chaque changement de route (router.push, <Link>, boutons précédent et suivant). Vous n’avez pas besoin d’appeler page().
Les clics, le scroll, les erreurs JavaScript, les Core Web Vitals et les liens sortants. Liste complète : Ce qui est capturé automatiquement.

Envoyer un événement depuis un composant

useAnalytics() ne fonctionne que dans un composant client :

components/SignupButton.tsx

"use client";
import { useAnalytics } from "@jichio/react";

export function SignupButton() {
  const analytics = useAnalytics();
  return (
    <button onClick={() => analytics.track("signup_completed", { plan: "pro" })}>
      Créer mon compte
    </button>
  );
}

Pour un événement émis côté serveur (Server Action, route API, webhook de paiement), utilisez l’API d’ingestion.

Désactiver Jichio sans clé

Pour que les environnements sans clé (preview, tests) n’envoient rien, entourez le provider d’un composant conditionnel :

components/JichioAnalytics.tsx

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

export function JichioAnalytics({ children }: { children: React.ReactNode }) {
  const apiKey = process.env.NEXT_PUBLIC_ANALYTICS_KEY;
  if (!apiKey) return <>{children}</>;
  return <AnalyticsProvider apiKey={apiKey}>{children}</AnalyticsProvider>;
}

Dans ce cas, useAnalytics() lève une erreur s’il est appelé sans provider. N’appelez useAnalytics() que dans des composants rendus sous le provider, ou rendez le provider systématiquement en production.

Utiliser une API auto-hébergée

Par défaut, les événements partent vers https://api.bissa.tech. Pour une API locale ou auto-hébergée, passez endpoint :

<AnalyticsProvider
  apiKey={process.env.NEXT_PUBLIC_ANALYTICS_KEY!}
  endpoint={process.env.NEXT_PUBLIC_ANALYTICS_ENDPOINT}
>

Aucun proxy ni réécriture d’URL n’est nécessaire.

Documentation

Installer sur Next.js

Prérequis

1. Installer le package

2. Déclarer la clé

3. Monter le provider

4. Redémarrer le serveur

Ce qui est suivi automatiquement

Envoyer un événement depuis un composant

Désactiver Jichio sans clé

Utiliser une API auto-hébergée

Étapes suivantes

​Prérequis

​1. Installer le package

​2. Déclarer la clé

​3. Monter le provider

​4. Redémarrer le serveur

​Ce qui est suivi automatiquement

​Envoyer un événement depuis un composant

​Désactiver Jichio sans clé

​Utiliser une API auto-hébergée

​Étapes suivantes

Prérequis

1. Installer le package

2. Déclarer la clé

3. Monter le provider

4. Redémarrer le serveur

Ce qui est suivi automatiquement

Envoyer un événement depuis un composant

Désactiver Jichio sans clé

Utiliser une API auto-hébergée

Étapes suivantes