@dotcms/analytics 1.1.1 → 1.2.0

package/README.md

@@ -10,7 +10,7 @@ Lightweight JavaScript SDK for tracking content-aware events in dotCMS. Works in
 <script
     src="ca.min.js"
     data-analytics-server="https://demo.dotcms.com"
-    data-analytics-auth="SITE_KEY"
+    data-analytics-auth="SITE_AUTH"
     data-analytics-auto-page-view="true"
     data-analytics-debug="false"></script>
 ```
@@ -25,14 +25,14 @@ npm install @dotcms/analytics
 import { initializeContentAnalytics } from '@dotcms/analytics';
 
 const analytics = initializeContentAnalytics({
-    siteKey: 'SITE_KEY',
+    siteAuth: 'SITE_AUTH',
     server: 'https://demo.dotcms.com'
 });
 
 analytics.track('page-loaded');
 ```
 
-### React
+### React (In Development)
 
 ```bash
 npm install @dotcms/analytics
@@ -42,7 +42,7 @@ npm install @dotcms/analytics
 import { DotContentAnalytics } from '@dotcms/analytics/react';
 
 const config = {
-    siteKey: 'SITE_KEY',
+    siteAuth: 'SITE_AUTH',
     server: 'https://demo.dotcms.com',
     autoPageView: true // Optional, default is true in React
 };
@@ -52,16 +52,48 @@ export function AppRoot() {
 }
 ```
 
+> **Note:** React API is subject to change during development.
+
 ## 📘 Core Concepts
 
-### Events
+### Page Views
+
+The `pageView()` method tracks page navigation events. **It automatically enriches the event with comprehensive data**, including:
 
-Track any user action as an event using `track('event-name', { payload })`.
+-   **Page data**: URL, title, referrer, path, protocol, search params, etc.
+-   **Device data**: Screen resolution, viewport size, language, user agent
+-   **UTM parameters**: Campaign tracking data (source, medium, campaign, etc.)
+-   **Context**: Site key, session ID, user ID, timestamp
 
-### Page Views
+You can optionally include custom data that will be sent **in addition** to all the automatic enrichment.
+
+**Method signature:**
+
+```typescript
+pageView(customData?: Record<string, unknown>): void
+```
+
+**Behavior:**
+
+-   **Standalone (IIFE)**: Auto-tracked only if `data-analytics-auto-page-view="true"`; otherwise call `window.dotAnalytics.pageView()` manually.
+-   **React**: In development (API may change)
+-   Custom data is optional and gets attached to the pageview event under the `custom` property alongside all automatically captured data.
+
+### Custom Events
 
--   React: Automatically tracked on route changes when using `DotContentAnalytics`.
--   Standalone: Auto-tracked only if `data-analytics-auto-page-view="true"`; otherwise call `window.dotAnalytics.pageView()`.
+The `track()` method allows you to track any custom user action with a unique event name and optional properties.
+
+**Method signature:**
+
+```typescript
+track(eventName: string, properties?: Record<string, unknown>): void
+```
+
+**Important:**
+
+-   `eventName` cannot be `"pageview"` (reserved for page view tracking)
+-   `eventName` should be a descriptive string like `"button-click"`, `"form-submit"`, `"video-play"`, etc.
+-   `properties` is optional and can contain any custom data relevant to the event
 
 ### Sessions
 
@@ -76,106 +108,287 @@ Track any user action as an event using `track('event-name', { payload })`.
 
 ## ⚙️ Configuration Options
 
-| Option         | Type      | Required | Default                             | Description                            |
+| Option | Type | Required | Default | Description |
 | -------------- | --------- | -------- | ----------------------------------- | -------------------------------------- |
-| `siteKey`      | `string`  | ✅       | -                                   | Site key from dotCMS Analytics app     |
-| `server`       | `string`  | ✅       | -                                   | Your dotCMS server URL                 |
-| `debug`        | `boolean` | ❌       | `false`                             | Enable verbose logging                 |
-| `autoPageView` | `boolean` | ❌       | React: `true` / Standalone: `false` | Auto track page views on route changes |
+| `siteAuth` | `string` | ✅ | - | Site auth from dotCMS Analytics app |
+| `server` | `string` | ✅ | - | Your dotCMS server URL |
+| `debug` | `boolean` | ❌ | `false` | Enable verbose logging |
+| `autoPageView` | `boolean` | ❌ | React: `true` / Standalone: `false` | Auto track page views on route changes |
+| `queueConfig` | `QueueConfig` | ❌ | See below | Event batching configuration |
+
+### Queue Configuration
+
+The `queueConfig` option controls event batching:
+
+-   **`false`**: Disable queuing, send events immediately
+-   **`undefined` (default)**: Enable queuing with default settings
+-   **`QueueConfig` object**: Enable queuing with custom settings
+
+| Option           | Type     | Default | Description                                      |
+| ---------------- | -------- | ------- | ------------------------------------------------ |
+| `eventBatchSize` | `number` | `15`    | Max events per batch - auto-sends when reached   |
+| `flushInterval`  | `number` | `5000`  | Time between flushes - sends pending events (ms) |
+
+**How it works:**
+
+-   ✅ Send immediately when `eventBatchSize` reached (e.g., 15 events)
+-   ✅ Send pending events every `flushInterval` (e.g., 5 seconds)
+-   ✅ Auto-flush on page navigation/close using `visibilitychange` + `pagehide` events
+-   Example: If you have 10 events and 5 seconds pass → sends those 10
+
+**About page unload handling:**
+
+The SDK uses modern APIs (`visibilitychange` + `pagehide`) instead of `beforeunload`/`unload` to ensure:
+
+-   ✅ Better reliability on mobile devices
+-   ✅ Compatible with browser back/forward cache (bfcache)
+-   ✅ Events are sent via `navigator.sendBeacon()` for guaranteed delivery
+-   ✅ No negative impact on page performance
+
+**Example: Disable queuing for immediate sends**
+
+```javascript
+const analytics = initializeContentAnalytics({
+    siteAuth: 'abc123',
+    server: 'https://your-dotcms.com',
+    queue: false // Send events immediately without batching
+});
+```
+
+**Example: Custom queue config**
+
+```javascript
+const analytics = initializeContentAnalytics({
+    siteAuth: 'abc123',
+    server: 'https://your-dotcms.com',
+    queue: {
+        eventBatchSize: 10, // Auto-send when 10 events queued
+        flushInterval: 3000 // Or send every 3 seconds
+    }
+});
+```
 
 ## 🛠️ Usage Examples
 
 ### Vanilla JavaScript
 
-**Manual Page View & Events**
+**Basic Page View**
 
 ```javascript
-// After init with the <script> tag the dotAnalytics is added to the window.
-window.dotAnalytics.track('cta-click', { button: 'Buy Now' });
+// After init with the <script> tag, dotAnalytics is added to the window
+// Automatically captures: page, device, UTM, context (session, user, site)
 window.dotAnalytics.pageView();
 ```
 
+**Page View with Additional Custom Data**
+
+```javascript
+// All automatic data (page, device, UTM, context) is STILL captured
+// Plus your custom properties are added under 'custom'
+window.dotAnalytics.pageView({
+    contentType: 'blog',
+    category: 'technology',
+    author: 'john-doe',
+    wordCount: 1500
+});
+
+// The server receives: page + device + utm + context + custom (your data)
+```
+
+**Track Custom Events**
+
+```javascript
+// Basic event tracking
+window.dotAnalytics.track('cta-click', {
+    button: 'Buy Now',
+    location: 'hero-section'
+});
+
+// Track form submission
+window.dotAnalytics.track('form-submit', {
+    formName: 'contact-form',
+    formType: 'lead-gen'
+});
+
+// Track video interaction
+window.dotAnalytics.track('video-play', {
+    videoId: 'intro-video',
+    duration: 120,
+    autoplay: false
+});
+```
+
 **Advanced: Manual Init with Custom Properties**
 
 ```javascript
 const analytics = initializeContentAnalytics({
-    siteKey: 'abc123',
+    siteAuth: 'abc123',
     server: 'https://your-dotcms.com',
     debug: true,
     autoPageView: false
 });
 
-analytics.track('custom-event', {
-    category: 'Marketing',
-    value: 'Banner Clicked'
+// Track custom events with properties
+analytics.track('product-view', {
+    productId: 'SKU-12345',
+    category: 'Electronics',
+    price: 299.99,
+    inStock: true
 });
 
-analytics.pageView();
+// Manual page view with custom data
+// Automatic enrichment (page, device, UTM, context) + your custom data
+analytics.pageView({
+    section: 'checkout',
+    step: 'payment',
+    cartValue: 299.99
+});
 ```
 
 ### React
 
-**Track Events**
+> **Note:** React integration is currently in development. The API may change.
+
+**Basic Setup**
 
 ```tsx
-import { useContentAnalytics } from '@dotcms/analytics/react';
+import { DotContentAnalytics } from '@dotcms/analytics/react';
 
-const { track } = useContentAnalytics({
-    siteKey: 'SITE_KEY',
-    server: 'https://demo.dotcms.com'
-});
+const config = {
+    siteAuth: 'SITE_KEY',
+    server: 'https://demo.dotcms.com',
+    autoPageView: true
+};
 
-track('cta-click', { label: 'Download PDF' });
+export function AppRoot() {
+    return <DotContentAnalytics config={config} />;
+}
 ```
 
-**Manual Page View**
+**Using the Hook**
 
 ```tsx
 import { useContentAnalytics } from '@dotcms/analytics/react';
 
-const { pageView } = useContentAnalytics({
-    siteKey: 'SITE_KEY',
-    server: 'https://demo.dotcms.com'
-});
-useEffect(() => {
-    pageView();
-}, []);
-```
+function MyComponent() {
+    const { track, pageView } = useContentAnalytics({
+        siteAuth: 'SITE_AUTH',
+        server: 'https://demo.dotcms.com'
+    });
 
-**Advanced: Manual Tracking with Router**
-
-```tsx
-// Next.js App Router is automatically tracked by <DotContentAnalytics />
-// For other routers, you can call pageView on location change
-import { useLocation } from 'react-router-dom';
-import { useContentAnalytics } from '@dotcms/analytics/react';
+    // Track custom events (same API as vanilla JS)
+    const handleClick = () => {
+        track('button-click', { label: 'CTA Button' });
+    };
 
-const { pageView } = useContentAnalytics({
-    siteKey: 'SITE_KEY',
-    server: 'https://demo.dotcms.com'
-});
-const location = useLocation();
-
-useEffect(() => {
-    pageView();
-}, [location]);
+    return <button onClick={handleClick}>Click Me</button>;
+}
 ```
 
 ## API Reference
 
 ```typescript
 interface DotCMSAnalytics {
-    track: (eventName: string, payload?: Record<string, unknown>) => void;
-    pageView: () => void;
+    /**
+     * Track a page view event with optional custom data
+     * @param customData - Optional object with custom properties to attach to the pageview
+     */
+    pageView: (customData?: Record<string, unknown>) => void;
+
+    /**
+     * Track a custom event
+     * @param eventName - Name of the custom event (cannot be "pageview")
+     * @param properties - Optional object with event-specific properties
+     */
+    track: (eventName: string, properties?: Record<string, unknown>) => void;
+}
+```
+
+### Page View Event Structure
+
+When you call `pageView(customData?)`, the SDK **automatically enriches** the event with comprehensive data and sends:
+
+```typescript
+{
+    context: {                     // 🤖 AUTOMATIC - Identity & Session
+        site_key: string;          //    Your site key
+        session_id: string;        //    Current session ID
+        user_id: string;           //    Anonymous user ID
+        device: {                  // 🤖 AUTOMATIC - Device & Browser Info
+            screen_resolution: string;  // Screen size
+            language: string;           // Browser language
+            viewport_width: string;     // Viewport width
+            viewport_height: string;    // Viewport height
+        }
+    },
+    events: [{
+        event_type: "pageview",
+        local_time: string,        // 🤖 AUTOMATIC - ISO 8601 timestamp with timezone
+        data: {
+            page: {                // 🤖 AUTOMATIC - Page Information
+                url: string;       //    Full URL
+                title: string;     //    Page title
+                referrer: string;  //    Referrer URL
+                path: string;      //    Path
+                doc_host: string;  //    Hostname
+                doc_protocol: string;  //  Protocol (http/https)
+                doc_search: string;    //  Query string
+                doc_hash: string;      //  URL hash
+                doc_encoding: string;  //  Character encoding
+            },
+            utm?: {                // 🤖 AUTOMATIC - Campaign Tracking (if present in URL)
+                source: string;    //    utm_source
+                medium: string;    //    utm_medium
+                campaign: string;  //    utm_campaign
+                term: string;      //    utm_term
+                content: string;   //    utm_content
+            },
+            custom?: {             // 👤 YOUR DATA (optional)
+                // Any custom properties you pass to pageView(customData)
+                contentType?: string;
+                category?: string;
+                author?: string;
+                // ... any other properties
+            }
+        }
+    }]
 }
 ```
 
-**Enriched AnalyticsEvent includes:**
+**Key Points:**
+
+-   🤖 Most data is captured **automatically** - you don't need to provide it
+-   👤 `custom` is where **your optional data** goes
+-   All automatic data is always captured, even if you don't pass `customData`
 
--   `context`: siteKey, sessionId, userId
--   `page`: URL, title, referrer, path
--   `device`: screen size, language, viewport
--   `utm`: source, medium, campaign, term, etc.
+### Custom Event Structure
+
+When you call `track(eventName, properties)`, the following structure is sent:
+
+```typescript
+{
+    context: {
+        site_key: string;      // Your site key
+        session_id: string;    // Current session ID
+        user_id: string;       // Anonymous user ID
+        device: {              // 🤖 AUTOMATIC - Device & Browser Info
+            screen_resolution: string;  // Screen size
+            language: string;           // Browser language
+            viewport_width: string;     // Viewport width
+            viewport_height: string;    // Viewport height
+        }
+    },
+    events: [{
+        event_type: string,    // Your custom event name
+        local_time: string,    // ISO 8601 timestamp
+        data: {
+            custom: {
+                // Your properties object
+            }
+        }
+    }]
+}
+```
 
 ## Under the Hood
 
@@ -213,25 +426,25 @@ Standalone attributes to verify:
 -   Angular & Vue support
 -   Realtime dashboard
 
-## dotCMS Support
+## Support
 
-We offer multiple channels to get help with the dotCMS React SDK:
+We offer multiple channels to get help with the dotCMS Analytics SDK:
 
--   **GitHub Issues**: For bug reports and feature requests, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository.
--   **Community Forum**: Join our [community discussions](https://community.dotcms.com/) 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](https://helpdesk.dotcms.com/support/).
+-   **GitHub Issues**: For bug reports and feature requests, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository
+-   **Community Forum**: Join our [community discussions](https://community.dotcms.com/) to ask questions and share solutions
+-   **Stack Overflow**: Use the tag `dotcms-analytics` when posting questions
+-   **Enterprise Support**: Enterprise customers can access premium support through the [dotCMS Support Portal](https://helpdesk.dotcms.com/support/)
 
 When reporting issues, please include:
 
 -   SDK version you're using
--   React version
+-   Framework/library version (if applicable)
 -   Minimal reproduction steps
 -   Expected vs. actual behavior
 
-## How To Contribute
+## Contributing
 
-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:
+GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the dotCMS Analytics SDK! If you'd like to contribute, please follow these steps:
 
 1. Fork the repository [dotCMS/core](https://github.com/dotCMS/core)
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
@@ -241,7 +454,7 @@ GitHub pull requests are the preferred method to contribute code to dotCMS. We w
 
 Please ensure your code follows the existing style and includes appropriate tests.
 
-## Licensing Information
+## 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 several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://www.dotcms.com/cms-platform/features).
 

package/lib/core/dot-content-analytics.d.ts

@@ -1,4 +1,11 @@
-import { DotCMSAnalytics, DotCMSAnalyticsConfig } from './shared/dot-content-analytics.model';
+import { ANALYTICS_WINDOWS_ACTIVE_KEY, ANALYTICS_WINDOWS_CLEANUP_KEY } from '../../../../uve/src/internal.ts';
+import { DotCMSAnalytics, DotCMSAnalyticsConfig } from './shared/models';
+declare global {
+    interface Window {
+        [ANALYTICS_WINDOWS_ACTIVE_KEY]?: boolean;
+        [ANALYTICS_WINDOWS_CLEANUP_KEY]?: () => void;
+    }
+}
 /**
  * Creates an analytics instance for content analytics tracking.
  *

package/lib/core/dot-content-analytics.js

@@ -1,43 +1,46 @@
-import { Analytics as s } from "analytics";
+import { Analytics as a } from "analytics";
+import { ANALYTICS_WINDOWS_ACTIVE_KEY as r, ANALYTICS_WINDOWS_CLEANUP_KEY as s } from "../../uve/src/internal/constants.js";
 import { dotAnalytics as l } from "./plugin/dot-analytics.plugin.js";
-import { dotAnalyticsEnricherPlugin as a } from "./plugin/enricher/dot-analytics.enricher.plugin.js";
-import { dotAnalyticsIdentityPlugin as u } from "./plugin/identity/dot-analytics.identity.plugin.js";
-import { cleanupActivityTracking as c, updateSessionActivity as o } from "./shared/dot-content-analytics.activity-tracker.js";
-const f = (n) => {
-  if (!n.siteKey)
-    return console.error('DotContentAnalytics: Missing "siteKey" in configuration'), null;
-  if (!n.server)
-    return console.error('DotContentAnalytics: Missing "server" in configuration'), null;
-  const t = s({
+import { dotAnalyticsEnricherPlugin as c } from "./plugin/enricher/dot-analytics.enricher.plugin.js";
+import { dotAnalyticsIdentityPlugin as p } from "./plugin/identity/dot-analytics.identity.plugin.js";
+import { validateAnalyticsConfig as m } from "./shared/dot-content-analytics.utils.js";
+import { cleanupActivityTracking as u } from "./shared/dot-content-analytics.activity-tracker.js";
+const I = (n) => {
+  const o = m(n);
+  if (o)
+    return console.error(`DotCMS Analytics: Missing ${o.join(" and ")} in configuration`), typeof window < "u" && (window[r] = !1), null;
+  const i = a({
     app: "dotAnalytics",
     debug: n.debug,
     plugins: [
-      u(n),
+      p(n),
       // Inject identity context (user_id, session_id, local_tz)
-      a(),
-      // Enrich with page, device, utm data
+      c(),
+      // Enrich and clean payload with page, device, utm data and custom data
       l(n)
       // Send events to server
     ]
-  }), e = () => c();
-  return typeof window < "u" && (window.addEventListener("beforeunload", e), window.__dotAnalyticsCleanup = e), {
+  }), e = () => u();
+  return typeof window < "u" && (window.addEventListener("beforeunload", e), window[s] = e, window[r] = !0, window.dispatchEvent(new CustomEvent("dotcms:analytics:ready"))), {
     /**
      * Track a page view.
-     * @param {Record<string, unknown>} payload - The payload to track.
+     * Session activity is automatically updated by the identity plugin.
+     * @param payload - Optional custom data to include with the page view (any valid JSON object)
      */
-    pageView: (i = {}) => {
-      o(), t == null || t.page(i);
+    pageView: (t = {}) => {
+      i == null || i.page(t);
     },
     /**
      * Track a custom event.
-     * @param {string} eventName - The name of the event to track.
-     * @param {Record<string, unknown>} payload - The payload to track.
+     * Session activity is automatically updated by the identity plugin.
+     * @param eventName - The name of the event to track
+     * @param payload - Custom data to include with the event (any valid JSON object)
      */
-    track: (i, r = {}) => {
-      o(), t == null || t.track(i, r);
+    track: (t, d = {}) => {
+      i == null || i.track(t, d);
     }
   };
 };
 export {
-  f as initializeContentAnalytics
+  I as initializeContentAnalytics
 };

package/lib/core/plugin/dot-analytics.plugin.d.ts

@@ -1,30 +1,31 @@
-import { DotCMSAnalyticsConfig, DotCMSAnalyticsParams } from '../shared/dot-content-analytics.model';
+import { DotCMSAnalyticsConfig, DotCMSAnalyticsParams } from '../shared/models';
 /**
  * Analytics plugin for tracking page views and custom events in DotCMS applications.
  * This plugin handles sending analytics data to the DotCMS server, managing initialization,
  * and processing both automatic and manual tracking events.
+ * Supports optional queue management for batching events before sending.
  *
  * @param {DotCMSAnalyticsConfig} config - Configuration object containing API key, server URL,
- *                                     debug mode and auto page view settings
+ *                                     debug mode, auto page view settings, and queue config
  * @returns {Object} Plugin object with methods for initialization and event tracking
  */
 export declare const dotAnalytics: (config: DotCMSAnalyticsConfig) => {
     name: string;
     config: DotCMSAnalyticsConfig;
     /**
-     * Initialize the plugin
+     * Initialize the plugin with optional queue management
      */
     initialize: () => Promise<void>;
     /**
      * Track a page view event
-     * Takes enriched data from properties and creates final structured event
+     * The enricher plugin has already built the complete request body
      */
-    page: (params: DotCMSAnalyticsParams) => Promise<void>;
+    page: (params: DotCMSAnalyticsParams) => void;
     /**
      * Track a custom event
-     * Takes enriched data and sends it to the analytics server
+     * The enricher plugin has already built the complete request body
      */
-    track: (params: DotCMSAnalyticsParams) => Promise<void>;
+    track: (params: DotCMSAnalyticsParams) => void;
     /**
      * Check if the plugin is loaded
      */