SDK Analytics Installer

DotCMS SDK Analytics Installation Guide

This skill provides step-by-step instructions for installing and configuring the @dotcms/analytics SDK in the Next.js example project at /core/examples/nextjs.

Overview

The @dotcms/analytics SDK is dotCMS's official JavaScript library for tracking content-aware events and analytics. It provides:

• Automatic page view tracking
• Conversion tracking (purchases, downloads, sign-ups, etc.)
• Custom event tracking
• Session management (30-minute timeout)
• Anonymous user identity tracking
• UTM campaign parameter tracking
• Event batching/queuing for performance

🚨 Important: Understanding the Analytics Components

CRITICAL: useContentAnalytics() ALWAYS requires config as a parameter. The hook does NOT use React Context.

Component Roles

1. <DotContentAnalytics /> - Auto Page View Tracker

   • Only purpose: Automatically track pageviews on route changes
   • NOT a React Context Provider
   • Does NOT provide config to child components
   • Place in root layout for automatic pageview tracking

2. useContentAnalytics(config) - Manual Tracking Hook

   • Used for custom event tracking
   • ALWAYS requires config parameter
   • Import centralized config in each component that uses it

Correct Usage Pattern

// 1. Create centralized config file (once)
// /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. Add DotContentAnalytics to layout for auto pageview tracking (optional)
// /src/app/layout.js
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

<DotContentAnalytics config={analyticsConfig} />;

// 3. Import config in every component that uses the hook
// /src/components/MyComponent.js
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

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

Why centralize config? While you must import it in each component, centralizing prevents duplication and makes updates easier.

Quick Setup Summary

Here's the complete setup flow:

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

2. Create centralized config file
   └─> /src/config/analytics.config.js
       └─> export const analyticsConfig = { siteAuth, server, debug, ... }

3. (Optional) Add DotContentAnalytics for auto pageview tracking
   └─> /src/app/layout.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> <DotContentAnalytics config={analyticsConfig} />

4. Import config in EVERY component that uses the hook
   └─> /src/components/MyComponent.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> const { track } = useContentAnalytics(analyticsConfig) // ✅ Config required!

Key Benefits of Centralized Config:

• ✅ Single source of truth for configuration values
• ✅ Easy to update environment variables in one place
• ✅ Consistent config across all components
• ✅ Better than duplicating config in every file

Installation Steps

1. Install the Package

Navigate to the Next.js example directory and install the package:

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

2. Verify Installation

Check that the package was added to package.json:

grep "@dotcms/analytics" package.json

Expected output: "@dotcms/analytics": "latest" or similar version.

3. Create Centralized Analytics Configuration

Create a dedicated configuration file to centralize your analytics settings. This makes it easier to maintain and reuse across your application.

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

/**
 * Centralized analytics configuration for dotCMS Content Analytics
 *
 * This configuration is used by:
 * - DotContentAnalytics provider in layout.js
 * - useContentAnalytics() hook when used standalone (optional)
 *
 * Environment variables required:
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG (optional)
 */
export const analyticsConfig = {
  siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
  server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
  autoPageView: true, // Automatically track page views on route changes
  debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
  queue: {
    eventBatchSize: 15, // Send when 15 events are queued
    flushInterval: 5000, // Or send every 5 seconds (ms)
  },
};

Benefits of this approach:

• ✅ Single source of truth for analytics configuration
• ✅ Easy to import and reuse across components
• ✅ Centralized environment variable management
• ✅ Type-safe and IDE autocomplete friendly
• ✅ Easy to test and mock in unit tests

4. Configure Analytics in Next.js Layout

Update the root layout file to include the analytics provider using the centralized config.

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

Updated with Analytics (using centralized config):

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. Add Environment Variables

Create or update .env.local file in the Next.js project root:

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

# dotCMS Analytics Configuration
NEXT_PUBLIC_DOTCMS_AUTH_TOKEN={GENERATE TOKEN FROM USER PORTLET API ACCESS TOKEN}
NEXT_PUBLIC_DOTCMS_HOST={URL WHERE DOTCMS IS RUNNING}
NEXT_PUBLIC_DOTCMS_SITE_ID={SITE IDENTIFIER}
NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY={GENERATE KEY FROM CONTENT ANALYTICS APP}
NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST={SITE IDENTIFIER}
NEXT_PUBLIC_EXPERIMENTS_API_KEY={GENERATED KEY FROM THE EXPERIMENTS APP}
NEXT_PUBLIC_DOTCMS_MODE='production'
NODE_TLS_REJECT_UNAUTHORIZED=0

Important: Replace your_site_auth_key_here with your actual dotCMS Analytics site auth key. This can be obtained from the Analytics app in your dotCMS instance.

5. Add .env.local to .gitignore

Ensure the environment file is not committed to version control:

# Check if already ignored
grep ".env.local" /core/examples/nextjs/.gitignore

# If not present, add it
echo ".env.local" >> /core/examples/nextjs/.gitignore

Usage Examples

Basic Setup (Automatic Page Views)

With the configuration above, page views are automatically tracked on every route change. No additional code needed!

Manual Page View with Custom Data

Track page views with additional context:

"use client";

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

function MyComponent() {
  // ✅ ALWAYS pass config - import from centralized config file
  const { pageView } = useContentAnalytics(analyticsConfig);

  useEffect(() => {
    // Track page view with custom data
    pageView({
      contentType: "blog",
      category: "technology",
      author: "john-doe",
      wordCount: 1500,
    });
  }, []);

  return <div>Content here</div>;
}

Track Custom Events

Track specific user interactions:

"use client";

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

function CallToActionButton() {
  // ✅ ALWAYS pass config - import from centralized config file
  const { track } = useContentAnalytics(analyticsConfig);

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

  return <button Now</button>;
}

Form Submission Tracking

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

    // Track form submission
    track("form-submit", {
      formName: "contact-form",
      formType: "lead-gen",
      source: "homepage",
    });

    // Submit form...
  };

  return <form Form fields */}</form>;
}

Video/Media Interaction Tracking

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

E-commerce Product View Tracking

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

  return <div>{/* Product details */}</div>;
}

Conversion Tracking (E-commerce Purchase)

"use client";

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

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

  const handlePurchase = () => {
    // Process checkout logic here...
    // After successful payment confirmation:

    // Track conversion ONLY after successful purchase
    conversion("purchase", {
      value: product.price * quantity,
      currency: "USD",
      productId: product.sku,
      productName: product.title,
      quantity: quantity,
      category: product.category,
    });
  };

  return <button Purchase</button>;
}

Conversion Tracking (Lead Generation)

"use client";

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

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

  const handleDownload = () => {
    // Trigger download logic here...
    // After download is successfully completed:

    // Track conversion ONLY after successful download
    conversion("download", {
      fileType: "pdf",
      fileName: "whitepaper-2024.pdf",
      category: "lead-magnet",
    });
  };

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

Configuration Options

Analytics Config Object

Queue Configuration

Controls how events are batched and sent:

Disable Queuing (send immediately):

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  queue: false, // Send events immediately
};

Impression Tracking Configuration

Controls automatic tracking of content visibility:

Enable with defaults:

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  impressions: true, // 50% visible, 750ms dwell, 1000 max nodes
};

Custom thresholds:

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  impressions: {
    visibilityThreshold: 0.7, // Require 70% visible
    dwellMs: 1000, // Must be visible for 1 second
    maxNodes: 500, // Track max 500 elements
  },
};

How it works:

• ✅ Tracks contentlets marked with dotcms-analytics-contentlet class and data-dot-analytics-* attributes
• ✅ Uses Intersection Observer API for high performance and battery efficiency
• ✅ Only fires when element is ≥50% visible for ≥750ms (configurable)
• ✅ Only tracks during active tab (respects page visibility)
• ✅ One impression per contentlet per session (no duplicates)
• ✅ Automatically disabled in dotCMS editor mode

Click Tracking Configuration

Controls automatic tracking of user interactions with content elements.

Enable click tracking:

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  clicks: true, // Enable with 300ms throttle (fixed)
};

How it works:

• ✅ Tracks clicks on <a> and <button> elements within contentlets
• ✅ Contentlets must be marked with dotcms-analytics-contentlet class and data-dot-analytics-* attributes
• ✅ Captures semantic attributes (href, aria-label, data-*) and excludes CSS classes
• ✅ Throttles rapid clicks to prevent duplicate tracking (300ms fixed)
• ✅ Automatically disabled in dotCMS editor mode

Captured Data:

For each click, the SDK captures:

• Content Info: identifier, inode, title, content_type
• Element Info:
  • text - Button/link text (truncated to 100 chars)
  • type - Element type (a or button)
  • id - Element ID (required by backend, empty string if not present)
  • class - Element CSS classes (required by backend, empty string if not present)
  • href - Link destination as written in HTML (e.g., /signup not http://..., only for <a>, empty string for buttons)
  • attributes - Additional useful attributes (see below)
• Position Info:
  • viewport_offset_pct - Position relative to viewport (0-100%)
  • dom_index - Element position in DOM

Attributes Object:

The attributes object captures additional semantic data:

✅ Included (semantic/analytics value):

• data-* - Custom data attributes (e.g., data-category="primary-cta")
• aria-* - Accessibility attributes
• title, target - Standard HTML attributes

❌ Excluded (to avoid duplication):

• class - Already captured as top-level property
• id - Already captured as top-level property
• href - Already captured as top-level property
• data-dot-analytics-* - Internal SDK attributes

Adding Custom Analytics Metadata:

Use data-* attributes to enrich click tracking:

// In your Next.js component
<a
  href="/signup"
  id="cta-signup"
  data-category="primary-cta"
  data-campaign="summer-sale"
  aria-label="Sign up for free trial">
  Start Free Trial →
</a>

<button
  data-action="download"
  data-file-type="pdf"
  data-category="lead-magnet">
  Download Whitepaper
</button>

Complete Configuration Example:

// /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",
  queue: {
    eventBatchSize: 15,
    flushInterval: 5000,
  },
  impressions: {
    visibilityThreshold: 0.5, // 50% visible
    dwellMs: 750, // 750ms dwell time
    maxNodes: 1000, // Track up to 1000 elements
  },
  clicks: true, // Enable click tracking (300ms throttle, fixed)
};

Data Captured Automatically

The SDK automatically enriches events with:

Page View Events

• Page Data: URL, title, referrer, path, protocol, search params, hash
• Device Data: Screen resolution, viewport size, language, user agent
• UTM Parameters: Campaign tracking (source, medium, campaign, term, content)
• Context: Site key, session ID, user ID, timestamp

Custom Events

• Context: Site key, session ID, user ID
• Device Data: Screen resolution, language, viewport dimensions
• Custom Properties: Any data you pass to track()

Session Management

• Duration: 30-minute timeout of inactivity
• Reset Conditions:
  • At midnight UTC
  • When UTM campaign changes
• Storage: Uses dot_analytics_session_id in localStorage

Identity Tracking

• Anonymous User ID: Persisted across sessions
• Storage Key: dot_analytics_user_id
• Behavior: Generated automatically on first visit, reused on subsequent visits

Testing & Debugging

Enable Debug Mode

Set debug: true in config to see verbose logging:

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  debug: true, // Enable debug logging
};

Verify Events in Network Tab

1. Open browser DevTools � Network tab
2. Filter by: /api/v1/analytics/content/event
3. Perform actions in your app
4. Check request payloads to see captured data

Check Storage

Open browser DevTools � Application � Local Storage:

• dot_analytics_user_id - Anonymous user identifier
• dot_analytics_session_id - Current session ID
• dot_analytics_session_utm - UTM campaign data
• dot_analytics_session_start - Session start timestamp

Troubleshooting

Events Not Appearing

1. Verify Configuration:

   • Check siteAuth and server are correct
   • Enable debug: true to see console logs

2. Check Network Requests:

   • Look for requests to /api/v1/analytics/content/event
   • Verify they're returning 200 status

3. Editor Mode Detection:

   • Analytics are automatically disabled inside dotCMS editor
   • Test in preview or published mode

4. Environment Variables:

   • Ensure .env.local is loaded (restart dev server if needed)
   • Verify variable names start with NEXT_PUBLIC_

Queue Not Flushing

• Check eventBatchSize - might not be reaching threshold
• Verify flushInterval is appropriate for your use case
• Events auto-flush on page navigation/close via visibilitychange

Session Not Persisting

• Check localStorage is enabled in browser
• Verify no browser extensions are blocking storage
• Check console for storage-related errors

Config File Issues

1. Import Path Not Found:

   // ❌ Error: Cannot find module '@/config/analytics.config'
   

   • Verify the file exists at /src/config/analytics.config.js
   • Check your jsconfig.json or tsconfig.json has the @ alias configured:

     {
       "compilerOptions": {
         "paths": {
           "@/*": ["./src/*"]
         }
       }
     }
     

2. Undefined Config Values:

   // Config shows undefined for siteAuth or server
   

   • Verify environment variables are set in .env.local
   • Restart dev server after changing .env.local
   • Check variable names start with NEXT_PUBLIC_

3. Config Not Updated:

   • Clear Next.js cache: rm -rf .next
   • Restart dev server: npm run dev

Integration with Existing Next.js Example

The Next.js example at /core/examples/nextjs already uses other dotCMS SDK packages:

• @dotcms/client - Core API client
• @dotcms/experiments - A/B testing
• @dotcms/react - React components
• @dotcms/types - TypeScript types
• @dotcms/uve - Universal Visual Editor

Adding analytics complements these by providing:

• Usage tracking across all content types
• User behavior insights
• Campaign performance metrics
• Content engagement analytics

API Reference

Component: DotContentAnalytics

interface AnalyticsConfig {
  siteAuth: string;
  server: string;
  debug?: boolean;
  autoPageView?: boolean;
  queue?: QueueConfig | false;
}

interface QueueConfig {
  eventBatchSize?: number;
  flushInterval?: number;
}

<DotContentAnalytics config={analyticsConfig} />;

Hook: useContentAnalytics

interface ContentAnalyticsHook {
  pageView: (customData?: Record<string, unknown>) => void;
  track: (eventName: string, properties?: Record<string, unknown>) => void;
  conversion: (name: string, options?: Record<string, unknown>) => void;
}

// ✅ CORRECT: Always pass config - import from centralized config file
import { analyticsConfig } from "@/config/analytics.config";
const { pageView, track, conversion } = useContentAnalytics(analyticsConfig);

CRITICAL: The hook ALWAYS requires config as a parameter. There is no provider pattern for the hook - <DotContentAnalytics /> is only for auto pageview tracking and does NOT provide context to child components.

Always import and pass the centralized config from /config/analytics.config.js to ensure consistency.

Methods

pageView(customData?)

Track a page view with optional custom data. Automatically captures page, device, UTM, and context data.

Parameters:

• customData (optional): Object with custom properties to attach

Example:

pageView({
  contentType: "product",
  category: "electronics",
});

track(eventName, properties?)

Track a custom event with optional properties.

Parameters:

• eventName (required): String identifier for the event (cannot be "pageview" or "conversion")
• properties (optional): Object with event-specific data

Example:

track("button-click", {
  label: "Subscribe",
  location: "sidebar",
});

conversion(name, options?)

Track a conversion event (purchase, download, sign-up, etc.) with optional metadata.

⚠️ IMPORTANT: Conversion events are business events that should only be tracked after a successful action or completed goal. Tracking conversions on clicks or attempts (before success) diminishes their value as conversion metrics. Only track conversions when:

• ✅ Purchase is completed and payment is confirmed
• ✅ Download is successfully completed
• ✅ Sign-up form is submitted and account is created
• ✅ Form submission is successful and data is saved
• ✅ Any business goal is actually achieved

Parameters:

• name (required): String identifier for the conversion (e.g., "purchase", "download", "signup")
• options (optional): Object with conversion metadata (all properties go into custom object)

Examples:

// Basic conversion (after successful download)
conversion("download");

// Conversion with custom metadata (after successful purchase)
conversion("purchase", {
  value: 99.99,
  currency: "USD",
  productId: "SKU-12345",
});

// Conversion with additional context (after successful signup)
conversion("signup", {
  source: "homepage",
  plan: "premium",
});

Best Practices

1. Centralize Configuration: Create a dedicated config file (/config/analytics.config.js) for all analytics settings

   // ✅ GOOD: Centralized config file
   // /config/analytics.config.js
   export const analyticsConfig = {
     siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
     server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
     debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
     autoPageView: true,
   };
   
   // ❌ BAD: Inline config in multiple files
   // component1.js
   const config = { siteAuth: "...", server: "..." };
   // component2.js
   const config = { siteAuth: "...", server: "..." }; // Duplicate!
   

2. Always Import and Pass Config: The hook requires config as a parameter

   // ✅ CORRECT: Import centralized config in every component
   // MyComponent.js
   import { analyticsConfig } from "@/config/analytics.config";
   const { track } = useContentAnalytics(analyticsConfig);
   
   // ❌ WRONG: Inline config duplication
   // MyComponent.js
   const { track } = useContentAnalytics({
     siteAuth: "...", // Duplicated!
     server: "...", // Duplicated!
   });
   

3. Use DotContentAnalytics for Auto PageViews: Add to layout for automatic tracking

   // layout.js - For automatic pageview tracking only
   import { analyticsConfig } from "@/config/analytics.config";
   <DotContentAnalytics config={analyticsConfig} />;
   

4. Environment Variables: Always use environment variables for sensitive config (siteAuth)

5. Event Naming: Use consistent, descriptive event names (e.g., cta-click, not just click)

6. Custom Data: Include relevant context in event properties

7. Queue Configuration: Use default queue settings unless you have specific performance needs

8. Debug Mode: Enable only in development, disable in production

9. Auto Page Views: Keep enabled for SPAs (Next.js) to track route changes

Related Resources

• Analytics SDK README: /core/core-web/libs/sdk/analytics/README.md
• Package Location: /core/core-web/libs/sdk/analytics/
• Next.js Example: /core/examples/nextjs/

Quick Command Reference

# Install package
cd /core/examples/nextjs
npm install @dotcms/analytics

# Start Next.js dev server
npm run dev

# Build for production
npm run build

# Start production server
npm run start

# Verify installation
npm list @dotcms/analytics