@dotcms/analytics

@dotcms/analytics

@dotcms/analytics is the official dotCMS JavaScript library for Content Analytics that helps track events and analytics in your webapps. Available for both browser and React applications.

Features

• Simple Browser Integration: Easy to implement via script tags using IIFE implementation
• React Support: Built-in React components and hooks for seamless integration
• Event Tracking: Simple API to track custom events with additional properties
• Automatic PageView: Option to automatically track page views
• Debug Mode: Optional debug logging for development

Installation

npm install @dotcms/analytics

Or include the script in your HTML page:

<script src="ca.min.js"></script>

React Integration

Provider Setup

First, import the provider:

import { DotContentAnalyticsProvider } from '@dotcms/analytics/react';

Wrap your application with the DotContentAnalyticsProvider:

// Example configuration
const analyticsConfig = {
    apiKey: 'your-api-key-from-dotcms-analytics-app',
    server: 'https://your-dotcms-instance.com'
};

function App() {
    return (
        <DotContentAnalyticsProvider config={analyticsConfig}>
            <YourApp />
        </DotContentAnalyticsProvider>
    );
}

Tracking Custom Events

Use the useContentAnalytics hook to track custom events:

import { useContentAnalytics } from '@dotcms/analytics/react';

function Activity({ title, urlTitle }) {
    const { track } = useContentAnalytics();

    // First parameter: custom event name to identify the action
    // Second parameter: object with properties you want to track

    return <button onClick={() => track('btn-click', { title, urlTitle })}>See Details →</button>;
}

Manual Page View Tracking

To manually track page views, first disable automatic tracking in your config:

const analyticsConfig = {
    apiKey: 'your-api-key-from-dotcms-analytics-app',
    server: 'https://your-dotcms-instance.com',
    autoPageView: false // Disable automatic tracking
};

Then use the useContentAnalytics hook in your layout component:

import { useContentAnalytics } from '@dotcms/analytics/react';

function Layout({ children }) {
    const { pageView } = useContentAnalytics();

    useEffect(() => {
        pageView({
            // Add any custom properties you want to track
            myCustomValue: '2'
        });
    }, []);

    return <div>{children}</div>;
}

Browser Configuration

The script can be configured using data attributes:

• data-analytics-server: URL of the server where events will be sent. If not provided, the current domain will be used
• data-analytics-debug: Enables debug logging
• data-analytics-auto-page-view: Recommended for IIFE implementation. Enables automatic page view tracking
• data-analytics-key: (Required) API key for authentication

<!-- Example configuration -->
<script
    src="ca.min.js"
    data-analytics-server="http://localhost:8080"
    data-analytics-key="dev-key-123"
    data-analytics-auto-page-view
    data-analytics-debug></script>

<!-- Without automatic tracking - events must be sent manually -->
<script
    src="ca.min.js"
    data-analytics-server="http://localhost:8080"
    data-analytics-debug
    data-analytics-key="dev-key-123"></script>

Roadmap

The following features are planned for future releases:

1. Headless Support
   • Angular integration for event tracking

Contributing

GitHub pull requests are the preferred method to contribute code to dotCMS. Before any pull requests can be accepted, an automated tool will ask you to agree to the dotCMS Contributor's Agreement.

Licensing

dotCMS comes in multiple editions and as such is dual licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds a number of enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see the feature page.

Support

If you need help or have any questions, please open an issue in the GitHub repository.

Documentation

Always refer to the official DotCMS documentation for comprehensive guides and API references.

Getting Help

Source	Location
Installation	Installation
Documentation	Documentation
Videos	Helpful Videos
Forums/Listserv	via Google Groups
Twitter	@dotCMS
Main Site	dotCMS.com