Reddot UI Library

Docs
Client PostHog

Client PostHog

Initialisation et configuration du client PostHog dans une application Next.js

PostHog est une plateforme d'analyse produit open-source qui vous permet de suivre les comportements utilisateurs, et d'analyser des parcours utilisateurs via de l'AB testing. Ce module facilite l'intégration de PostHog dans votre application Next.js avec un support complet du rendu côté serveur (SSR).

Installation

$npx shadcn@latest add https://reddot.dottools.xyz/r/posthog.json

Structure des fichiers

L'installation ajoute trois fichiers importants :

  • instrumentation-client.ts : Configuration de PostHog côté client
  • components/lib/posthog/client.ts : Client PostHog pour utilisation côté serveur
  • components/lib/posthog/types.ts : Types TypeScript pour assurer la cohérence des événements et feature flags

Configuration

Ajoutez ou modifiez le fichier .env.local à la racine de votre projet avec les variables d'environnement suivantes :

NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
NEXT_PUBLIC_POSTHOG_KEY=your_posthog_key
  • NEXT_PUBLIC_POSTHOG_HOST : L'URL de l'instance PostHog (utilisez https://eu.i.posthog.com pour l'instance européenne ou https://app.posthog.com pour l'instance américaine)
  • NEXT_PUBLIC_POSTHOG_KEY : Votre clé d'API PostHog (projet)

Vous pouvez trouver ces valeurs dans votre dashboard PostHog sous Project Settings > Project API Key.

Instrumentation Next.js

Important : Si vous avez déjà un fichier instrumentation-client.ts dans votre projet, ne sélectionnez pas l'option "overwrite" lors de l'installation. Modifiez plutôt manuellement votre fichier existant en y ajoutant le code PostHog.

Le fichier instrumentation-client.ts est automatiquement détecté par Next.js et exécuté côté client.

Utilisation

Type Safety avec types.ts

Le fichier components/lib/posthog/types.ts contient des objets pour tous les événements et feature flags utilisés dans l'application. Cela permet d'assurer une cohérence dans les noms d'événements et d'éviter les erreurs de frappe.

Important : Vous devez éditer ce fichier pour ajouter vos propres événements et feature flags personnalisés.

Exemple de structure du fichier types.ts :

/**
 * Feature flags utilisés dans l'application
 * Ajustez selon votre configuration sur le dashboard PostHog
 */
export const FeatureFlags = {
  AB_TEST_ONBOARDING: 'ab-test-onboarding',
  ENABLE_NEW_FEATURE: 'enable-new-feature',
} as const;
 
export type FeatureFlags = (typeof FeatureFlags)[keyof typeof FeatureFlags];
 
/**
 * Variantes possibles pour les feature flags.
 * Il ne faut pas modifier ces valeurs.
 */
export const FlagsVariants = {
  CONTROL: 'control',
  TEST: 'test',
} as const;
 
export type FlagsVariants = (typeof FlagsVariants)[keyof typeof FlagsVariants];
 
/**
 * Exemple d'événements custom que l'on souhaite capturer
 * Ajustez selon vos besoins
 */
export const EventsCaptured = {
  START_CV_FLOW: 'start_cv_flow',
  COMPLETE_PROFILE: 'complete_profile',
  VIEW_PRODUCT: 'view_product',
} as const;
 
export type EventsCaptured = (typeof EventsCaptured)[keyof typeof EventsCaptured];

Suivi des événements

Utilisez les objets définis dans types.ts pour capturer des événements avec type safety :

'use client';
 
import { usePostHog } from 'components/lib/posthog/client';
import { EventsCaptured, FlagsVariants } from '@/components/lib/posthog/types';
 
export function MyComponent() {
  const posthog = usePostHog();
 
  const handleClick = () => {
    posthog.capture(EventsCaptured.START_CV_FLOW, {
      property: 'value',
    });
  };
 
  return <button onClick={handleClick}>Cliquez-moi</button>;
}

Identification des utilisateurs

Pour identifier un utilisateur après sa connexion :

'use client';
 
import { usePostHog } from 'components/lib/posthog/client';
 
export function UserProfile({ user }) {
  const posthog = usePostHog();
 
  useEffect(() => {
    if (user?.id) {
      posthog?.identify(user.id, {
        name: user.name,
        email: user.email,
      });
    }
  }, [user, posthog]);
 
  return <div>Profil utilisateur</div>;
}

Suivi des pages vues

Le client PostHog suit automatiquement les changements de page dans votre application Next.js. Vous n'avez pas besoin de code supplémentaire pour cette fonctionnalité.

Fonctionnalités avancées

Feature Flags

PostHog permet d'utiliser des feature flags pour activer ou désactiver des fonctionnalités. Utilisez les enums pour une meilleure type safety :

'use client';
 
import { usePostHog } from 'components/lib/posthog/client';
import { FeatureFlags } from '@/components/lib/posthog/types';
import { useState, useEffect } from 'react';
 
export function FeatureComponent() {
  const posthog = usePostHog();
  const [hasFeature, setHasFeature] = useState(false);
 
  useEffect(() => {
    if (posthog) {
      const featureEnabled = posthog.isFeatureEnabled(FeatureFlags.ENABLE_NEW_FEATURE);
      setHasFeature(featureEnabled);
    }
  }, [posthog]);
 
  if (!hasFeature) return null;
 
  return <div>Nouvelle fonctionnalité</div>;
}

A/B Testing

Vous pouvez configurer des tests A/B avec PostHog :

Server-side

import PostHogClient, { getDistinctId } from '@/components/lib/posthog/client';
import { FeatureFlags, FlagsVariants } from '@/components/lib/posthog/types';
 
export default async function Page() {
  const posthog = PostHogClient();
 
  const distinctId = await getDistinctId();
  const abTestFlag = await posthog.getFeatureFlag(FeatureFlags.AB_TEST_ONBOARDING, distinctId);
 
  await posthog.shutdown();
 
  return abTestFlag === FlagsVariants.TEST ? <div>Nouvelle fonctionnalité</div> : <div>ancienne fonctionnalité</div>;
}

Client-side

'use client';
 
import { useFeatureFlagVariantKey } from 'posthog-js/react';
import { FeatureFlags, FlagsVariants } from '@/components/lib/posthog/types';
 
export function ABTestComponent() {
  const abTestFlag = useFeatureFlagVariantKey(FeatureFlags.AB_TEST_ONBOARDING);
 
  if (abTestFlag === FlagsVariants.TEST) {
    return <div>Nouvelle fonctionnalité</div>;
  }
 
  return <div>ancienne fonctionnalité</div>;
}

Bonnes pratiques

  1. Limitez le nombre d'événements : Suivez uniquement les événements pertinents pour éviter de surcharger votre instance PostHog.

  2. Utilisez des propriétés cohérentes : Standardisez les noms et les propriétés des événements pour faciliter l'analyse.

  3. Testez en environnement de développement : Utilisez un projet PostHog séparé pour le développement et la production.

Points importants pour l'utilisation côté serveur

  1. Toujours appeler shutdown() : Pour éviter les fuites de mémoire, appelez toujours posthog.shutdown() après avoir utilisé PostHog côté serveur.

  2. ID distinct : Vous devez fournir un ID distinct pour identifier l'utilisateur lors de l'utilisation des feature flags côté serveur.

  3. Type casting : Utilisez le type casting avec les objets définis dans types.ts pour garantir la type safety des valeurs de feature flags.

Ressources additionnelles