Guía de Instalación del SDK de Analytics de DotCMS

Esta skill proporciona instrucciones paso a paso para instalar y configurar el SDK @dotcms/analytics en el proyecto de ejemplo de Next.js en /core/examples/nextjs.

Resumen

El SDK @dotcms/analytics es la biblioteca oficial de JavaScript de dotCMS para rastrear eventos y análisis relacionados con el contenido. Proporciona:

Rastreo automático de vistas de página
Rastreo de conversiones (compras, descargas, registros, etc.)
Rastreo de eventos personalizados
Gestión de sesiones (tiempo de espera de 30 minutos)
Rastreo de identidad de usuario anónimo
Rastreo de parámetros de campaña UTM
Agrupación/colas de eventos para rendimiento

🚨 Importante: Cómo entender los Componentes de Analytics

CRÍTICO: useContentAnalytics() SIEMPRE requiere un config como parámetro. El hook NO usa React Context.

Roles de los Componentes

<DotContentAnalytics /> - Rastreador Automático de Vistas de Página
- Único propósito: Rastrear automáticamente las vistas de página en cambios de ruta
- NO es un Proveedor de Contexto de React
- NO proporciona config a componentes hijos
- Colocar en el layout raíz para rastreo automático de vistas de página
useContentAnalytics(config) - Hook de Rastreo Manual
- Se usa para rastreo de eventos personalizados
- SIEMPRE requiere el parámetro config
- Importar la config centralizada en cada componente que lo use

Patrón de Uso Correcto

// 1. Crear archivo de config centralizada (una vez)
// /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. Añadir DotContentAnalytics al layout para rastreo automático (opcional)
// /src/app/layout.js
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

<DotContentAnalytics config={analyticsConfig} />;

// 3. Importar config en cada componente que use el hook
// /src/components/MyComponent.js
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

const { track } = useContentAnalytics(analyticsConfig); // ✅ ¡Config obligatorio!

¿Por qué centralizar la config? Aunque debes importarla en cada componente, centralizar evita la duplicación y facilita las actualizaciones.

Resumen de Configuración Rápida

Aquí está el flujo de configuración completo:

1. Instalar el paquete
   └─> npm install @dotcms/analytics

2. Crear archivo de config centralizada
   └─> /src/config/analytics.config.js
       └─> export const analyticsConfig = { siteAuth, server, debug, ... }

3. (Opcional) Añadir DotContentAnalytics para rastreo automático
   └─> /src/app/layout.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> <DotContentAnalytics config={analyticsConfig} />

4. Importar config en CADA componente que use el hook
   └─> /src/components/MyComponent.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> const { track } = useContentAnalytics(analyticsConfig) // ✅ ¡Config obligatorio!

Beneficios Clave de la Config Centralizada:

✅ Fuente única de verdad para los valores de configuración
✅ Fácil de actualizar variables de entorno en un solo lugar
✅ Config consistente en todos los componentes
✅ Mejor que duplicar la config en cada archivo

Pasos de Instalación

1. Instalar el Paquete

Navega al directorio de ejemplo de Next.js e instala el paquete:

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

2. Verificar la Instalación

Comprueba que el paquete se ha añadido a package.json:

grep "@dotcms/analytics" package.json

Salida esperada: "@dotcms/analytics": "latest" o una versión similar.

3. Crear Configuración Centralizada de Analytics

Crea un archivo de configuración dedicado para centralizar tus ajustes de analytics. Esto facilita el mantenimiento y la reutilización en toda tu aplicación.

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

/**
 * Configuración centralizada de analytics para dotCMS Content Analytics
 *
 * Esta configuración es utilizada por:
 * - El proveedor DotContentAnalytics en layout.js
 * - El hook useContentAnalytics() cuando se usa de forma independiente (opcional)
 *
 * Variables de entorno requeridas:
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG (opcional)
 */
export const analyticsConfig = {
  siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
  server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
  autoPageView: true, // Rastrear automáticamente vistas de página en cambios de ruta
  debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
  queue: {
    eventBatchSize: 15, // Enviar cuando haya 15 eventos en cola
    flushInterval: 5000, // O enviar cada 5 segundos (ms)
  },
};

Beneficios de este enfoque:

✅ Fuente única de verdad para la configuración de analytics
✅ Fácil de importar y reutilizar entre componentes
✅ Gestión centralizada de variables de entorno
✅ Seguro para tipos y amigable con el autocompletado del IDE
✅ Fácil de probar y simular en pruebas unitarias

4. Configurar Analytics en el Layout de Next.js

Actualiza el archivo de layout raíz para incluir el proveedor de analytics usando la config centralizada.

Archivo: /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>
  );
}

Actualizado con Analytics (usando config centralizada):

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>
  );
}

4. Añadir Variables de Entorno

Crea o actualiza el archivo .env.local en la raíz del proyecto Next.js:

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

# Configuración de dotCMS Analytics
NEXT_PUBLIC_DOTCMS_SITE_AUTH=tu_clave_de_sitio_aqui
NEXT_PUBLIC_DOTCMS_SERVER=https://tu-servidor-dotcms.com

Importante: Reemplaza tu_clave_de_sitio_aqui con tu clave real de autenticación del sitio de dotCMS Analytics. Puedes obtenerla desde la aplicación Analytics en tu instancia de dotCMS.

5. Añadir `.env.local` a `.gitignore`

Asegúrate de que el archivo de entorno no se suba al control de versiones:

# Comprobar si ya está ignorado
grep ".env.local" /core/examples/nextjs/.gitignore

# Si no está presente, añadirlo
echo ".env.local" >> /core/examples/nextjs/.gitignore

Ejemplos de Uso

Configuración Básica (Vistas de Página Automáticas)

Con la configuración anterior, las vistas de página se rastrean automáticamente en cada cambio de ruta. ¡No se necesita código adicional!

Vista de Página Manual con Datos Personalizados

Rastrea vistas de página con contexto adicional:

"use client";

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

function MyComponent() {
  // ✅ SIEMPRE pasar config - importar desde el archivo de config centralizada
  const { pageView } = useContentAnalytics(analyticsConfig);

  useEffect(() => {
    // Rastrear vista de página con datos personalizados
    pageView({
      contentType: "blog",
      category: "technology",
      author: "john-doe",
      wordCount: 1500,
    });
  }, []);

  return <div>Contenido aquí</div>;
}

Rastrear Eventos Personalizados

Rastrea interacciones específicas del usuario:

"use client";

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

function CallToActionButton() {
  // ✅ SIEMPRE pasar config - importar desde el archivo de config centralizada
  const { track } = useContentAnalytics(analyticsConfig);

  const handleClick = () => {
    // Rastrear evento personalizado
    track("cta-click", {
      button: "Comprar Ahora",
      location: "hero-section",
      price: 299.99,
    });
  };

  return <button onClick={handleClick}>Comprar Ahora</button>;
}

Rastreo de Envío de Formularios

"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();

    // Rastrear envío de formulario
    track("form-submit", {
      formName: "contact-form",
      formType: "lead-gen",
      source: "homepage",
    });

    // Enviar formulario...
  };

  return <form onSubmit={handleSubmit}>{/* Campos del formulario */}</form>;
}

Rastreo de Interacción con Video/Medios

"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}>
      {/* Fuentes de video */}
    </video>
  );
}

Rastreo de Vista de Producto en Comercio Electrónico

"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(() => {
    // Rastrear vista de producto
    track("product-view", {
      productId: product.sku,
      productName: product.title,
      category: product.category,
      price: product.price,
      inStock: product.inventory > 0,
    });
  }, [product]);

  return <div>{/* Detalles del producto */}</div>;
}

Rastreo de Conversión (Compra en Comercio Electrónico)

"use client";

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

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

  const handlePurchase = () => {
    // Procesar lógica de pago aquí...
    // Después de la confirmación exitosa del pago:

    // Rastrear conversión SOLO después de una compra exitosa
    conversion("purchase", {
      value: product.price * quantity,
      currency: "USD",
      productId: product.sku,
      productName: product.title,
      quantity: quantity,
      category: product.category,
    });
  };

  return <button onClick={handlePurchase}>Completar Compra</button>;
}

Rastreo de Conversión (Generación de Leads)

"use client";

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

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

  const handleDownload = () => {
    // Activar lógica de descarga aquí...
    // Después de que la descarga se complete exitosamente:

    // Rastrear conversión SOLO después de una descarga exitosa
    conversion("download", {
      fileType: "pdf",
      fileName: "whitepaper-2024.pdf",
      category: "lead-magnet",
    });
  };

  return (
    <button id="download-btn" onClick={handleDownload}>
      Descargar Whitepaper
    </button>
  );
}

Opciones de Configuración

Objeto de Configuración de Analytics

Opción	Tipo	Requerido	Por Defecto	Descripción
`siteAuth`	`string`	Sí	-	Clave de autenticación del sitio de dotCMS Analytics
`server`	`string`	Sí	-	URL de tu servidor dotCMS
`debug`	`boolean`	No	`false`	Habilitar registro verboso para depuración
`autoPageView`	`boolean`	No	`true` (React)	Rastrear automáticamente vistas de página en cambios de ruta
`queue`	`QueueConfig \| false`	No	Configuración de cola por defecto	Configuración de agrupación de eventos
`impressions`	`ImpressionConfig \| boolean`	No	`false`	Rastreo de impresiones de contenido (deshabilitado por defecto)
`clicks`	`boolean`	No	`false`	Rastreo de clics en contenido con aceleración de 300ms (deshabilitado por defecto)

Configuración de Cola

Controla cómo se agrupan y envían los eventos:

Opción	Tipo	Por Defecto	Descripción
`eventBatchSize`	`number`	`15`	Máximo de eventos por lote - se envía automáticamente al alcanzarlo
`flushInterval`	`number`	`5000`	Tiempo en ms entre envíos

Deshabilitar Cola (enviar inmediatamente):

const analyticsConfig = {
  siteAuth: "tu_clave",
  server: "https://tu-servidor.com",
  queue: false, // Enviar eventos inmediatamente
};

Configuración de Rastreo de Impresiones

Controla el rastreo automático de visibilidad del contenido:

Opción	Tipo	Por Defecto	Descripción
`throttleDelay`	`number`	`200`	Tiempo de aceleración en ms entre verificaciones de visibilidad
`observerDelay`	`number`	`500`	Retraso en ms antes de que el observador Intersection comience a rastrear
`rootMargin`	`string`	`'0px'`	Margen del viewport para la detección de visibilidad
`scrollThreshold`	`number`	`0.5`	Umbral de visibilidad antes de que se active la impresión (0.0 - 1.0)
`trackViews`	`boolean`	`false`	Rastrear automáticamente vistas de contenido cuando se vuelven visibles
`trackDuration`	`boolean`	`false`	Rastrear cuánto tiempo (ms) el contenido es visible

Microck/ordinary-claude-skills

¿Qué es ordinary-claude-skills?

Preguntar en tu IA favorita

Documentación