Guide d'installation du SDK Analytics DotCMS

Cette compétence fournit des instructions pas à pas pour installer et configurer le SDK @dotcms/analytics dans le projet d'exemple Next.js situé dans /core/examples/nextjs.

Aperçu

Le SDK @dotcms/analytics est la bibliothèque JavaScript officielle de dotCMS pour le suivi d'événements et d'analytics contextuels. Il offre :

Suivi automatique des pages vues
Suivi des conversions (achats, téléchargements, inscriptions, etc.)
Suivi d'événements personnalisés
Gestion des sessions (délai d'expiration de 30 minutes)
Suivi d'identité utilisateur anonyme
Suivi des paramètres de campagne UTM
Mise en lots/tampon des événements pour les performances

🚨 Important : Comprendre les composants Analytics

CRITIQUE : useContentAnalytics() nécessite TOUJOURS une configuration en paramètre. Ce hook n'utilise PAS React Context.

Rôles des composants

<DotContentAnalytics /> - Traqueur automatique de pages vues
- Objectif unique : suivre automatiquement les pages vues lors des changements de route
- N'est PAS un fournisseur de contexte React
- Ne fournit PAS de configuration aux composants enfants
- Placez-le dans la mise en page racine pour le suivi automatique des pages vues
useContentAnalytics(config) - Hook de suivi manuel
- Utilisé pour le suivi d'événements personnalisés
- Nécessite TOUJOURS le paramètre config
- Importez la configuration centralisée dans chaque composant qui l'utilise

Modèle d'utilisation correct

// 1. Créer un fichier de configuration centralisé (une fois)
// /src/config/analytics.config.js
export const analyticsConfig = {
  siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
  server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
  autoPageView: true,
  debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
};

// 2. Ajouter DotContentAnalytics à la mise en page pour le suivi automatique des pages vues (optionnel)
// /src/app/layout.js
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

<DotContentAnalytics config={analyticsConfig} />;

// 3. Importer la configuration dans chaque composant qui utilise le hook
// /src/components/MyComponent.js
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

const { track } = useContentAnalytics(analyticsConfig); // ✅ Configuration requise !

Pourquoi centraliser la configuration ? Bien que vous deviez l'importer dans chaque composant, la centralisation évite la duplication et facilite les mises à jour.

Résumé de la configuration rapide

Voici le flux de configuration complet :

1. Installer le package
   └─> npm install @dotcms/analytics

2. Créer un fichier de configuration centralisé
   └─> /src/config/analytics.config.js
       └─> export const analyticsConfig = { siteAuth, server, debug, ... }

3. (Optionnel) Ajouter DotContentAnalytics pour le suivi automatique des pages vues
   └─> /src/app/layout.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> <DotContentAnalytics config={analyticsConfig} />

4. Importer la configuration dans CHAQUE composant qui utilise le hook
   └─> /src/components/MyComponent.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> const { track } = useContentAnalytics(analyticsConfig) // ✅ Configuration requise !

Avantages clés de la configuration centralisée :

✅ Source unique de vérité pour les valeurs de configuration
✅ Mise à jour facile des variables d'environnement en un seul endroit
✅ Configuration cohérente dans tous les composants
✅ Meilleur que de dupliquer la configuration dans chaque fichier

Étapes d'installation

1. Installer le package

Accédez au répertoire d'exemple Next.js et installez le package :

cd /core/examples/nextjs
npm install @dotcms/analytics

2. Vérifier l'installation

Vérifiez que le package a été ajouté au fichier package.json :

grep "@dotcms/analytics" package.json

Sortie attendue : "@dotcms/analytics": "latest" ou une version similaire.

3. Créer une configuration analytics centralisée

Créez un fichier de configuration dédié pour centraliser vos paramètres analytics. Cela facilite la maintenance et la réutilisation dans l'ensemble de votre application.

Fichier : /core/examples/nextjs/src/config/analytics.config.js

/**
 * Configuration analytics centralisée pour dotCMS Content Analytics
 *
 * Cette configuration est utilisée par :
 * - Le fournisseur DotContentAnalytics dans layout.js
 * - Le hook useContentAnalytics() lorsqu'il est utilisé de manière autonome (optionnel)
 *
 * Variables d'environnement requises :
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG (optionnel)
 */
export const analyticsConfig = {
  siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
  server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
  autoPageView: true, // Suivre automatiquement les pages vues lors des changements de route
  debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
  queue: {
    eventBatchSize: 15, // Envoyer lorsque 15 événements sont en file d'attente
    flushInterval: 5000, // Ou envoyer toutes les 5 secondes (ms)
  },
};

Avantages de cette approche :

✅ Source unique de vérité pour la configuration analytics
✅ Importation et réutilisation faciles dans les composants
✅ Gestion centralisée des variables d'environnement
✅ Typage sécurisé et autocomplétion IDE
✅ Facile à tester et à simuler dans les tests unitaires

4. Configurer Analytics dans la mise en page Next.js

Mettez à jour le fichier de mise en page racine pour inclure le fournisseur analytics en utilisant la configuration centralisée.

Fichier : /core/examples/nextjs/src/app/layout.js

import { Inter } from "next/font/google";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
}

Mis à jour avec Analytics (en utilisant la configuration centralisée) :

import { Inter } from "next/font/google";
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <DotContentAnalytics config={analyticsConfig} />
        {children}
      </body>
    </html>
  );
}

5. Ajouter les variables d'environnement

Créez ou mettez à jour le fichier .env.local à la racine du projet Next.js :

Fichier : /core/examples/nextjs/.env.local

# Configuration dotCMS Analytics
NEXT_PUBLIC_DOTCMS_SITE_AUTH=votre_cle_auth_site_ici
NEXT_PUBLIC_DOTCMS_SERVER=https://votre-serveur-dotcms.com

Important : Remplacez votre_cle_auth_site_ici par votre véritable clé d'authentification de site dotCMS Analytics. Celle-ci peut être obtenue depuis l'application Analytics dans votre instance dotCMS.

6. Ajouter `.env.local` au fichier `.gitignore`

Assurez-vous que le fichier d'environnement n'est pas commité dans le contrôle de version :

# Vérifier s'il est déjà ignoré
grep ".env.local" /core/examples/nextjs/.gitignore

# S'il n'est pas présent, l'ajouter
echo ".env.local" >> /core/examples/nextjs/.gitignore

Exemples d'utilisation

Configuration de base (pages vues automatiques)

Avec la configuration ci-dessus, les pages vues sont automatiquement suivies à chaque changement de route. Aucun code supplémentaire n'est nécessaire !

Page vue manuelle avec données personnalisées

Suivez les pages vues avec un contexte supplémentaire :

"use client";

import { useEffect } from "react";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function MyComponent() {
  // ✅ Toujours passer la configuration - importée depuis le fichier centralisé
  const { pageView } = useContentAnalytics(analyticsConfig);

  useEffect(() => {
    // Suivre la page vue avec des données personnalisées
    pageView({
      contentType: "blog",
      category: "technologie",
      author: "jean-dupont",
      wordCount: 1500,
    });
  }, []);

  return <div>Contenu ici</div>;
}

Suivre des événements personnalisés

Suivez des interactions utilisateur spécifiques :

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function CallToActionButton() {
  // ✅ Toujours passer la configuration - importée depuis le fichier centralisé
  const { track } = useContentAnalytics(analyticsConfig);

  const handleClick = () => {
    // Suivre un événement personnalisé
    track("cta-click", {
      button: "Acheter maintenant",
      location: "section-hero",
      price: 299.99,
    });
  };

  return <button onClick={handleClick}>Acheter maintenant</button>;
}

Suivi de soumission de formulaire

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function ContactForm() {
  const { track } = useContentAnalytics(analyticsConfig);

  const handleSubmit = async (e) => {
    e.preventDefault();

    // Suivre la soumission du formulaire
    track("form-submit", {
      formName: "formulaire-contact",
      formType: "generation-leads",
      source: "page-accueil",
    });

    // Soumettre le formulaire...
  };

  return <form onSubmit={handleSubmit}>{/* Champs du formulaire */}</form>;
}

Suivi d'interaction vidéo/média

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function VideoPlayer({ videoId }) {
  const { track } = useContentAnalytics(analyticsConfig);

  const handlePlay = () => {
    track("video-play", {
      videoId,
      duration: 120,
      autoplay: false,
    });
  };

  const handleComplete = () => {
    track("video-complete", {
      videoId,
      watchPercentage: 100,
    });
  };

  return (
    <video onPlay={handlePlay} onEnded={handleComplete}>
      {/* Sources vidéo */}
    </video>
  );
}

Suivi de vue de produit e-commerce

"use client";

import { useEffect } from "react";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function ProductPage({ product }) {
  const { track } = useContentAnalytics(analyticsConfig);

  useEffect(() => {
    // Suivre la vue du produit
    track("product-view", {
      productId: product.sku,
      productName: product.title,
      category: product.category,
      price: product.price,
      inStock: product.inventory > 0,
    });
  }, [product]);

  return <div>{/* Détails du produit */}</div>;
}

Suivi de conversion (achat e-commerce)

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function CheckoutButton({ product, quantity }) {
  const { conversion } = useContentAnalytics(analyticsConfig);

  const handlePurchase = () => {
    // Logique de paiement ici...
    // Après confirmation de paiement réussie :

    // Suivre la conversion UNIQUEMENT après un achat réussi
    conversion("purchase", {
      value: product.price * quantity,
      currency: "EUR",
      productId: product.sku,
      productName: product.title,
      quantity: quantity,
      category: product.category,
    });
  };

  return <button onClick={handlePurchase}>Finaliser l'achat</button>;
}

Suivi de conversion (génération de leads)

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function DownloadWhitepaper() {
  const { conversion } = useContentAnalytics(analyticsConfig);

  const handleDownload = () => {
    // Logique de téléchargement ici...
    // Après que le téléchargement soit terminé avec succès :

    // Suivre la conversion UNIQUEMENT après un téléchargement réussi
    conversion("download", {
      fileType: "pdf",
      fileName: "livre-blanc-2024.pdf",
      category: "aimant-a-leads",
    });
  };

  return (
    <button id="download-btn" onClick={handleDownload}>
      Télécharger le livre blanc
    </button>
  );
}

Options de configuration

Objet de configuration Analytics

Option	Type	Requis	Défaut	Description
`siteAuth`	`string`	Oui	-	Clé d'authentification du site depuis dotCMS Analytics
`server`	`string`	Oui	-	L'URL de votre serveur dotCMS
`debug`	`boolean`	Non	`false`	Activer la journalisation détaillée pour le débogage
`autoPageView`	`boolean`	Non	`true` (React)	Suivre automatiquement les pages vues lors des changements de route
`queue`	`QueueConfig \| false`	Non	Paramètres de file par défaut	Configuration du regroupement d'événements
`impressions`	`ImpressionConfig \| boolean`	Non	`false`	Suivi des impressions de contenu (désactivé par défaut)
`clicks`	`boolean`	Non	`false`	Suivi des clics sur le contenu avec une temporisation de 300 ms (désactivé par défaut)

Configuration de la file d'attente

Contrôle la manière dont les événements sont regroupés et envoyés :

Option	Type	Défaut	Description
`eventBatchSize`	`number`	`15`	Nombre max d'événements par lot - envoi auto quand atteint
`flushInterval`	`number`	`5000`	Temps en ms entre les envois

Désactiver la mise en file d'attente (envoyer immédiatement) :

const analyticsConfig = {
  siteAuth: "votre_cle",
  server: "https://votre-serveur.com",
  queue: false, // Envoyer les événements immédiatement
};

Configuration du suivi des impressions

Contrôle le suivi automatique de la visibilité du contenu :

| Option | Type | Défaut | Description

…

[Le contenu a été tronqué pour la traduction. Les sections suivantes concernent les options de configuration avancées et les liens de référence.]

Microck/ordinary-claude-skills

Qu'est-ce que ordinary-claude-skills ?

Demander à votre IA préférée

Documentation