SDK: Analytics Library

Lightweight JavaScript SDK for tracking content-aware events in dotCMS. Works in vanilla JS and React apps. Angular & Vue support coming soon.

🚀 Quick Start#

---

Vanilla JavaScript#

CDN (Script Tag - Auto Page View)

<script
    src="ca.min.js"
    data-analytics-server="https://demo.dotcms.com"
    data-analytics-key="SITE_KEY"
    data-analytics-auto-page-view></script>

npm (ES Module)

npm install @dotcms/analytics

import { initializeContentAnalytics } from '@dotcms/analytics';

const analytics = initializeContentAnalytics({
    siteKey: 'SITE_KEY',
    server: 'https://demo.dotcms.com'
});

analytics.track('page-loaded');

React#

npm install @dotcms/analytics

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

const config = {
    siteKey: 'SITE_KEY',
    server: 'https://demo.dotcms.com',
    autoPageView: true // Optional, default is true
};

<DotContentAnalyticsProvider config={config}>
    <App />
</DotContentAnalyticsProvider>;

📘 Core Concepts#

---

Events#

Track any user action as an event using track('event-name', { payload }).

Page Views#

Tracked automatically (or manually) on route changes.

Sessions#

• 30-minute timeout
• Resets at midnight UTC
• New session if UTM campaign changes

Identity#

• Anonymous user ID persisted across sessions
• Stored in dot_analytics_user_id

⚙️ Configuration Options#

---

🛠️ Usage Examples#

---

Vanilla JavaScript#

Manual Page View & Events

// After init with the <script> tag the dotAnalytics is added to the window.
window.dotAnalytics.track('cta-click', { button: 'Buy Now' });
window.dotAnalytics.pageView();

Advanced: Manual Init with Custom Properties

const analytics = initializeContentAnalytics({
    siteKey: 'abc123',
    server: 'https://your-dotcms.com',
    debug: true,
    autoPageView: false
});

analytics.track('custom-event', {
    category: 'Marketing',
    value: 'Banner Clicked'
});

analytics.pageView();

React#

Track Events

const { track } = useContentAnalytics();
track('cta-click', { label: 'Download PDF' });

Manual Page View

const { pageView } = useContentAnalytics();
useEffect(() => {
    pageView();
}, []);

Advanced: Manual Tracking with Router

import { useLocation } from 'react-router-dom';
const { pageView } = useContentAnalytics();
const location = useLocation();

useEffect(() => {
    pageView();
}, [location]);

API Reference#

---

interface DotCMSAnalytics {
    track: (eventName: string, payload?: Record<string, unknown>) => void;
    pageView: () => void;
}

Enriched AnalyticsEvent includes:

• context: siteKey, sessionId, userId
• page: URL, title, referrer, path
• device: screen size, language, viewport
• utm: source, medium, campaign, term, etc.

Under the Hood#

---

Storage Keys#

• dot_analytics_user_id
• dot_analytics_session_id
• dot_analytics_session_utm
• dot_analytics_session_start

Editor Detection#

Analytics are disabled when inside the dotCMS editor.

Debugging & Troubleshooting#

---

Not seeing events?

• Ensure siteKey & server are correct
• Enable debug mode
• Check network requests to: https://your-server/api/v1/analytics/content/event
• Avoid using inside dotCMS editor (auto-disabled)

Roadmap#

---

• Scroll depth & file download tracking
• Form interaction analytics
• Angular & Vue support
• Realtime dashboard

dotCMS Support#

---

We offer multiple channels to get help with the dotCMS React SDK:

• GitHub Issues: For bug reports and feature requests, please open an issue in the GitHub repository.
• Community Forum: Join our community discussions to ask questions and share solutions.
• Stack Overflow: Use the tag dotcms-react when posting questions.
• Enterprise Support: Enterprise customers can access premium support through the dotCMS Support Portal.

When reporting issues, please include:

• SDK version you're using
• React version
• Minimal reproduction steps
• Expected vs. actual behavior

How To Contribute#

---

GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the DotCMS UVE SDK! If you'd like to contribute, please follow these steps:

1. Fork the repository dotCMS/core
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.

Licensing Information#

---

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 several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see the feature page.

This SDK is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).

Learn more at dotcms.com.