Guia de Instalação do SDK de Analytics do DotCMS

Esta skill fornece instruções passo a passo para instalar e configurar o SDK @dotcms/analytics no projeto de exemplo Next.js em /core/examples/nextjs.

Visão Geral

O SDK @dotcms/analytics é a biblioteca JavaScript oficial do dotCMS para rastrear eventos e análises relacionados a conteúdo. Ele oferece:

Rastreamento automático de visualizações de página
Rastreamento de conversões (compras, downloads, inscrições, etc.)
Rastreamento de eventos personalizados
Gerenciamento de sessão (timeout de 30 minutos)
Rastreamento de identidade anônima do usuário
Rastreamento de parâmetros de campanha UTM
Agrupamento/fila de eventos para desempenho

🚨 Importante: Entendendo os Componentes de Analytics

CRÍTICO: useContentAnalytics() SEMPRE requer config como parâmetro. O hook NÃO usa React Context.

Funções dos Componentes

<DotContentAnalytics /> - Rastreador Automático de Visualizações de Página
- Único propósito: Rastrear automaticamente visualizações de página em mudanças de rota
- NÃO é um Provedor de Contexto React
- NÃO fornece config para componentes filhos
- Coloque no layout raiz para rastreamento automático de visualizações de página
useContentAnalytics(config) - Hook de Rastreamento Manual
- Usado para rastreamento de eventos personalizados
- SEMPRE requer o parâmetro config
- Importe a config centralizada em cada componente que o utiliza

Padrão de Uso Correto

// 1. Crie um arquivo de configuração centralizado (uma 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. Adicione DotContentAnalytics ao layout para rastreamento automático de visualizações (opcional)
// /src/app/layout.js
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

<DotContentAnalytics config={analyticsConfig} />;

// 3. Importe a config em todo componente que usar o hook
// /src/components/MyComponent.js
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

const { track } = useContentAnalytics(analyticsConfig); // ✅ Config obrigatória!

Por que centralizar a config? Embora você deva importá-la em cada componente, centralizar evita duplicação e facilita as atualizações.

Resumo Rápido de Configuração

Aqui está o fluxo completo de configuração:

1. Instalar o pacote
   └─> npm install @dotcms/analytics

2. Criar arquivo de configuração centralizado
   └─> /src/config/analytics.config.js
       └─> export const analyticsConfig = { siteAuth, server, debug, ... }

3. (Opcional) Adicionar DotContentAnalytics para rastreamento automático de visualizações
   └─> /src/app/layout.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> <DotContentAnalytics config={analyticsConfig} />

4. Importar config em TODO componente que usar o hook
   └─> /src/components/MyComponent.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> const { track } = useContentAnalytics(analyticsConfig) // ✅ Config obrigatória!

Principais Benefícios da Config Centralizada:

✅ Fonte única da verdade para valores de configuração
✅ Fácil de atualizar variáveis de ambiente em um só lugar
✅ Config consistente em todos os componentes
✅ Melhor do que duplicar config em cada arquivo

Etapas de Instalação

1. Instalar o Pacote

Navegue até o diretório de exemplo Next.js e instale o pacote:

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

2. Verificar a Instalação

Verifique se o pacote foi adicionado ao package.json:

grep "@dotcms/analytics" package.json

Saída esperada: "@dotcms/analytics": "latest" ou versão similar.

3. Criar Configuração de Analytics Centralizada

Crie um arquivo de configuração dedicado para centralizar suas configurações de analytics. Isso facilita a manutenção e reutilização em toda a aplicação.

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

/**
 * Configuração centralizada de analytics para dotCMS Content Analytics
 *
 * Esta configuração é usada por:
 * - Provedor DotContentAnalytics no layout.js
 * - Hook useContentAnalytics() quando usado de forma independente (opcional)
 *
 * Variáveis de ambiente necessárias:
 * - 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, // Rastreia automaticamente visualizações de página em mudanças de rota
  debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
  queue: {
    eventBatchSize: 15, // Envia quando 15 eventos estão na fila
    flushInterval: 5000, // Ou envia a cada 5 segundos (ms)
  },
};

Benefícios desta abordagem:

✅ Fonte única da verdade para configuração de analytics
✅ Fácil de importar e reutilizar entre componentes
✅ Gerenciamento centralizado de variáveis de ambiente
✅ Type-safe e amigável para autocomplete do IDE
✅ Fácil de testar e simular em testes unitários

4. Configurar Analytics no Layout do Next.js

Atualize o arquivo de layout raiz para incluir o provedor de analytics usando a config centralizada.

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

Atualizado com 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. Adicionar Variáveis de Ambiente

Crie ou atualize o arquivo .env.local na raiz do projeto Next.js:

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

# Configuração de Analytics do dotCMS
NEXT_PUBLIC_DOTCMS_SITE_AUTH=your_site_auth_key_here
NEXT_PUBLIC_DOTCMS_SERVER=https://your-dotcms-server.com

Importante: Substitua your_site_auth_key_here pela sua chave de autenticação do dotCMS Analytics. Ela pode ser obtida no aplicativo Analytics da sua instância dotCMS.

5. Adicionar `.env.local` ao `.gitignore`

Garanta que o arquivo de ambiente não seja commitado no controle de versão:

# Verifique se já está ignorado
grep ".env.local" /core/examples/nextjs/.gitignore

# Se não estiver presente, adicione-o
echo ".env.local" >> /core/examples/nextjs/.gitignore

Exemplos de Uso

Configuração Básica (Visualizações Automáticas de Página)

Com a configuração acima, as visualizações de página são rastreadas automaticamente a cada mudança de rota. Nenhum código adicional é necessário!

Visualização Manual de Página com Dados Personalizados

Rastreie visualizações de página com contexto adicional:

"use client";

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

function MyComponent() {
  // ✅ SEMPRE passe a config - importe do arquivo de configuração centralizado
  const { pageView } = useContentAnalytics(analyticsConfig);

  useEffect(() => {
    // Rastreie visualização de página com dados personalizados
    pageView({
      contentType: "blog",
      category: "technology",
      author: "john-doe",
      wordCount: 1500,
    });
  }, []);

  return <div>Conteúdo aqui</div>;
}

Rastrear Eventos Personalizados

Rastreie interações específicas do usuário:

"use client";

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

function CallToActionButton() {
  // ✅ SEMPRE passe a config - importe do arquivo de configuração centralizado
  const { track } = useContentAnalytics(analyticsConfig);

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

  return <button onClick={handleClick}>Buy Now</button>;
}

Rastreamento de Envio de Formulário

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

    // Rastreie envio de formulário
    track("form-submit", {
      formName: "contact-form",
      formType: "lead-gen",
      source: "homepage",
    });

    // Envie o formulário...
  };

  return <form onSubmit={handleSubmit}>{/* Campos do formulário */}</form>;
}

Rastreamento de Interação com Vídeo/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}>
      {/* Fontes de vídeo */}
    </video>
  );
}

Rastreamento de Visualização de Produto (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(() => {
    // Rastreie visualização de produto
    track("product-view", {
      productId: product.sku,
      productName: product.title,
      category: product.category,
      price: product.price,
      inStock: product.inventory > 0,
    });
  }, [product]);

  return <div>{/* Detalhes do produto */}</div>;
}

Rastreamento de Conversão (Compra no 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 = () => {
    // Processe a lógica de checkout aqui...
    // Após confirmação de pagamento bem-sucedida:

    // Rastreie conversão SOMENTE após compra bem-sucedida
    conversion("purchase", {
      value: product.price * quantity,
      currency: "USD",
      productId: product.sku,
      productName: product.title,
      quantity: quantity,
      category: product.category,
    });
  };

  return <button onClick={handlePurchase}>Complete Purchase</button>;
}

Rastreamento de Conversão (Geração de Leads)

"use client";

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

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

  const handleDownload = () => {
    // Acione a lógica de download aqui...
    // Após o download ser concluído com sucesso:

    // Rastreie conversão SOMENTE após download bem-sucedido
    conversion("download", {
      fileType: "pdf",
      fileName: "whitepaper-2024.pdf",
      category: "lead-magnet",
    });
  };

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

Opções de Configuração

Objeto de Configuração de Analytics

Opção	Tipo	Obrigatório	Padrão	Descrição
`siteAuth`	`string`	Sim	-	Chave de autenticação do dotCMS Analytics
`server`	`string`	Sim	-	URL do seu servidor dotCMS
`debug`	`boolean`	Não	`false`	Ativa logs detalhados para depuração
`autoPageView`	`boolean`	Não	`true` (React)	Rastreia automaticamente visualizações de página em mudanças de rota
`queue`	`QueueConfig \| false`	Não	Configurações de fila padrão	Configuração de agrupamento de eventos
`impressions`	`ImpressionConfig \| boolean`	Não	`false`	Rastreamento de impressão de conteúdo (desativado por padrão)
`clicks`	`boolean`	Não	`false`	Rastreamento de clique com limite de 300ms (desativado por padrão)

Configuração de Fila

Controla como os eventos são agrupados e enviados:

Opção	Tipo	Padrão	Descrição
`eventBatchSize`	`number`	`15`	Máx. de eventos por lote - envia automaticamente quando atingido
`flushInterval`	`number`	`5000`	Tempo em ms entre envios

Desabilitar Fila (enviar imediatamente):

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  queue: false, // Envia eventos imediatamente
};

Configuração de Rastreamento de Impressão

Controla o rastreamento automático da visibilidade do conteúdo:

…

[truncado para tradução]

Microck/ordinary-claude-skills

O que é ordinary-claude-skills?

Perguntar na sua IA favorita

Documentação