@dotcms/analytics 0.0.1-beta.9 → 1.0.0

package/README.md

@@ -1,159 +1,226 @@
-# @dotcms/analytics
+# dotCMS Content Analytics SDK (@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.
+Lightweight JavaScript SDK for tracking content-aware events in dotCMS. Works in vanilla JS and React apps. Angular & Vue support coming soon.
 
-## Features
+## 🚀 Quick Start
 
--   **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
+### Vanilla JavaScript
 
-## Installation
+**CDN (Script Tag - Auto Page View)**
+
+```html
+<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)**
 
 ```bash
 npm install @dotcms/analytics
 ```
 
-Or include the script in your HTML page:
+```javascript
+import { initializeContentAnalytics } from '@dotcms/analytics';
 
-```html
-<script src="ca.min.js"></script>
-```
+const analytics = initializeContentAnalytics({
+    siteKey: 'SITE_KEY',
+    server: 'https://demo.dotcms.com'
+});
 
-## React Integration
+analytics.track('page-loaded');
+```
 
-### Provider Setup
+### React
 
-First, import the provider:
+```bash
+npm install @dotcms/analytics
+```
 
 ```tsx
 import { DotContentAnalyticsProvider } from '@dotcms/analytics/react';
-```
 
-Wrap your application with the `DotContentAnalyticsProvider`:
-
-```tsx
-// Example configuration
-const analyticsConfig = {
-    apiKey: 'your-api-key-from-dotcms-analytics-app',
-    server: 'https://your-dotcms-instance.com'
+const config = {
+    siteKey: 'SITE_KEY',
+    server: 'https://demo.dotcms.com',
+    autoPageView: true // Optional, default is true
 };
 
-function App() {
-    return (
-        <DotContentAnalyticsProvider config={analyticsConfig}>
-            <YourApp />
-        </DotContentAnalyticsProvider>
-    );
-}
+<DotContentAnalyticsProvider config={config}>
+    <App />
+</DotContentAnalyticsProvider>;
 ```
 
-### Tracking Custom Events
+## 📘 Core Concepts
 
-Use the `useContentAnalytics` hook to track custom events:
+### Events
 
-```tsx
-import { useContentAnalytics } from '@dotcms/analytics/react';
+Track any user action as an event using `track('event-name', { payload })`.
 
-function Activity({ title, urlTitle }) {
-    const { track } = useContentAnalytics();
+### Page Views
 
-    // First parameter: custom event name to identify the action
-    // Second parameter: object with properties you want to track
+Tracked automatically (or manually) on route changes.
 
-    return <button onClick={() => track('btn-click', { title, urlTitle })}>See Details →</button>;
-}
+### 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
+
+| 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`  | ❌       | `true`  | Auto track page views on route changes |
+| `redirectFn`   | `function` | ❌       | -       | Custom handler for redirects           |
+
+## 🛠️ Usage Examples
+
+### Vanilla JavaScript
+
+**Manual Page View & Events**
+
+```javascript
+// After init with the <script> tag the dotAnalytics is added to the window.
+window.dotAnalytics.track('cta-click', { button: 'Buy Now' });
+window.dotAnalytics.pageView();
 ```
 
-### Manual Page View Tracking
+**Advanced: Manual Init with Custom Properties**
+
+```javascript
+const analytics = initializeContentAnalytics({
+    siteKey: 'abc123',
+    server: 'https://your-dotcms.com',
+    debug: true,
+    autoPageView: false
+});
 
-To manually track page views, first disable automatic tracking in your config:
+analytics.track('custom-event', {
+    category: 'Marketing',
+    value: 'Banner Clicked'
+});
+
+analytics.pageView();
+```
+
+### React
+
+**Track Events**
 
 ```tsx
-const analyticsConfig = {
-    apiKey: 'your-api-key-from-dotcms-analytics-app',
-    server: 'https://your-dotcms-instance.com',
-    autoPageView: false // Disable automatic tracking
-};
+const { track } = useContentAnalytics();
+track('cta-click', { label: 'Download PDF' });
 ```
 
-Then use the `useContentAnalytics` hook in your layout component:
+**Manual Page View**
 
 ```tsx
-import { useContentAnalytics } from '@dotcms/analytics/react';
+const { pageView } = useContentAnalytics();
+useEffect(() => {
+    pageView();
+}, []);
+```
+
+**Advanced: Manual Tracking with Router**
+
+```tsx
+import { useLocation } from 'react-router-dom';
+const { pageView } = useContentAnalytics();
+const location = useLocation();
 
-function Layout({ children }) {
-    const { pageView } = useContentAnalytics();
+useEffect(() => {
+    pageView();
+}, [location]);
+```
 
-    useEffect(() => {
-        pageView({
-            // Add any custom properties you want to track
-            myCustomValue: '2'
-        });
-    }, []);
+## API Reference
 
-    return <div>{children}</div>;
+```typescript
+interface DotCMSAnalytics {
+    track: (eventName: string, payload?: Record<string, unknown>) => void;
+    pageView: () => void;
 }
 ```
 
-## Browser Configuration
+**Enriched AnalyticsEvent includes:**
 
-The script can be configured using data attributes:
+-   `context`: siteKey, sessionId, userId
+-   `page`: URL, title, referrer, path
+-   `device`: screen size, language, viewport
+-   `utm`: source, medium, campaign, term, etc.
 
--   **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
+## Under the Hood
 
-```html
-<!-- 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>
+### Storage Keys
 
-<!-- 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>
-```
+-   `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
 
-The following features are planned for future releases:
+-   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:
 
-2. **Headless Support**
-    - Angular integration for event tracking
+-   **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/).
 
-## Contributing
+When reporting issues, please include:
 
-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](https://gist.github.com/wezell/85ef45298c48494b90d92755b583acb3).
+-   SDK version you're using
+-   React version
+-   Minimal reproduction steps
+-   Expected vs. actual behavior
 
-## Licensing
+## How To Contribute
 
-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](http://dotcms.com/cms-platform/features).
+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:
 
-## Support
+1. Fork the repository [dotCMS/core](https://github.com/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
 
-If you need help or have any questions, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository.
+Please ensure your code follows the existing style and includes appropriate tests.
 
-## Documentation
+## Licensing Information
 
-Always refer to the official [DotCMS documentation](https://www.dotcms.com/docs/latest/) for comprehensive guides and API references.
+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).
 
-## Getting Help
+This SDK is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).
 
-| Source          | Location                                                            |
-| --------------- | ------------------------------------------------------------------- |
-| Installation    | [Installation](https://dotcms.com/docs/latest/installation)         |
-| Documentation   | [Documentation](https://dotcms.com/docs/latest/table-of-contents)   |
-| Videos          | [Helpful Videos](http://dotcms.com/videos/)                         |
-| Forums/Listserv | [via Google Groups](https://groups.google.com/forum/#!forum/dotCMS) |
-| Twitter         | @dotCMS                                                             |
-| Main Site       | [dotCMS.com](https://dotcms.com/)                                   |
+[Learn more ](https://www.dotcms.com)at [dotcms.com](https://www.dotcms.com).

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

@@ -1,9 +1,9 @@
-import { DotAnalytics, DotContentAnalyticsConfig } from './shared/dot-content-analytics.model';
+import { DotCMSAnalytics, DotCMSAnalyticsConfig } from './shared/dot-content-analytics.model';
 
 /**
- * Creates an analytics instance.
+ * Creates an analytics instance for content analytics tracking.
  *
- * @param {DotContentAnalyticsConfig} config - The configuration object for the analytics instance.
- * @returns {DotAnalytics} - The analytics instance.
+ * @param {DotCMSAnalyticsConfig} config - The configuration object for the analytics instance.
+ * @returns {DotCMSAnalytics} - The analytics instance.
  */
-export declare const initializeContentAnalytics: (config: DotContentAnalyticsConfig) => DotAnalytics;
+export declare const initializeContentAnalytics: (config: DotCMSAnalyticsConfig) => DotCMSAnalytics | null;

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

@@ -1,24 +1,43 @@
-import { createAnalyticsInstance as o } from "./shared/dot-content-analytics.utils.js";
-const i = (r) => {
-  const t = o(r);
-  return {
+import { Analytics as s } from "analytics";
+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({
+    app: "dotAnalytics",
+    debug: n.debug,
+    plugins: [
+      u(n),
+      // Inject identity context (user_id, session_id, local_tz)
+      a(),
+      // Enrich with page, device, utm data
+      l(n)
+      // Send events to server
+    ]
+  }), e = () => c();
+  return typeof window < "u" && (window.addEventListener("beforeunload", e), window.__dotAnalyticsCleanup = e), {
     /**
      * Track a page view.
      * @param {Record<string, unknown>} payload - The payload to track.
      */
-    pageView: (e = {}) => {
-      t == null || t.page(e);
+    pageView: (i = {}) => {
+      o(), t == null || t.page(i);
     },
     /**
      * Track a custom event.
      * @param {string} eventName - The name of the event to track.
      * @param {Record<string, unknown>} payload - The payload to track.
      */
-    track: (e, n = {}) => {
-      t == null || t.track(e, n);
+    track: (i, r = {}) => {
+      o(), t == null || t.track(i, r);
     }
   };
 };
 export {
-  i as initializeContentAnalytics
+  f as initializeContentAnalytics
 };

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

@@ -1,29 +1,31 @@
-import { DotAnalyticsParams, DotContentAnalyticsConfig } from '../shared/dot-content-analytics.model';
+import { DotCMSAnalyticsConfig, DotCMSAnalyticsParams } from '../shared/dot-content-analytics.model';
 
 /**
  * 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.
  *
- * @param {DotAnalyticsConfig} config - Configuration object containing API key, server URL,
+ * @param {DotCMSAnalyticsConfig} config - Configuration object containing API key, server URL,
  *                                     debug mode and auto page view settings
  * @returns {Object} Plugin object with methods for initialization and event tracking
  */
-export declare const dotAnalytics: (config: DotContentAnalyticsConfig) => {
+export declare const dotAnalytics: (config: DotCMSAnalyticsConfig) => {
     name: string;
-    config: DotContentAnalyticsConfig;
+    config: DotCMSAnalyticsConfig;
     /**
      * Initialize the plugin
      */
-    initialize: (params: DotAnalyticsParams) => Promise<void>;
+    initialize: () => Promise<void>;
     /**
      * Track a page view event
+     * Takes enriched data from properties and creates final structured event
      */
-    page: (params: DotAnalyticsParams) => Promise<void>;
+    page: (params: DotCMSAnalyticsParams) => Promise<void>;
     /**
      * Track a custom event
+     * Takes enriched data and sends it to the analytics server
      */
-    track: (params: DotAnalyticsParams) => Promise<void>;
+    track: (params: DotCMSAnalyticsParams) => Promise<void>;
     /**
      * Check if the plugin is loaded
      */

package/lib/dotAnalytics/plugin/dot-analytics.plugin.js

@@ -1,55 +1,79 @@
-import { sendAnalyticsEventToServer as r } from "../shared/dot-content-analytics.http.js";
-const s = (a) => {
-  let n = !1;
+import { EVENT_TYPES as y } from "../shared/dot-content-analytics.constants.js";
+import { sendAnalyticsEventToServer as c } from "../shared/dot-content-analytics.http.js";
+const p = (v) => {
+  let r = !1;
   return {
     name: "dot-analytics",
-    config: a,
+    config: v,
     /**
      * Initialize the plugin
      */
-    initialize: (o) => {
-      const { config: i, payload: t } = o;
-      if (i.debug && console.warn("DotAnalytics: Initialized with config", i), n = !0, i.autoPageView) {
-        const e = {
-          ...t.properties,
-          key: i.apiKey
-        };
-        return r(e, i);
-      }
-      return Promise.resolve();
-    },
+    initialize: () => (r = !0, Promise.resolve()),
     /**
      * Track a page view event
+     * Takes enriched data from properties and creates final structured event
      */
-    page: (o) => {
-      const { config: i, payload: t } = o;
-      if (!n)
+    page: (a) => {
+      const { config: t, payload: e } = a, { context: n, page: o, device: i, utm: s, local_time: l } = e;
+      if (!r)
         throw new Error("DotAnalytics: Plugin not initialized");
-      const e = {
-        ...t.properties,
-        key: i.apiKey
+      if (!n || !o || !i || !l)
+        throw new Error("DotAnalytics: Missing required payload data for pageview event");
+      const d = {
+        context: n,
+        events: [
+          {
+            event_type: y.PAGEVIEW,
+            local_time: l,
+            data: {
+              page: o,
+              device: i,
+              ...s && { utm: s }
+            }
+          }
+        ]
       };
-      return r(e, i);
+      return t.debug && console.warn("DotAnalytics: Pageview event to send:", d), c(d, t);
     },
+    // TODO: Fix this when we haver the final design for the track event
     /**
      * Track a custom event
+     * Takes enriched data and sends it to the analytics server
      */
-    track: (o) => {
-      const { config: i, payload: t } = o;
-      if (!n)
+    track: (a) => {
+      const { config: t, payload: e } = a;
+      if (!r)
         throw new Error("DotAnalytics: Plugin not initialized");
-      const e = {
-        ...t.properties,
-        key: i.apiKey
+      if ("events" in e && Array.isArray(e.events)) {
+        const o = e, i = {
+          context: o.context,
+          events: o.events
+        };
+        return t.debug && console.warn("DotAnalytics: Track event to send:", i), c(i, t);
+      }
+      if (!e.context || !e.local_time)
+        throw new Error("DotAnalytics: Missing required payload data for track event");
+      const n = {
+        context: e.context,
+        events: [
+          {
+            event_type: y.TRACK,
+            local_time: e.local_time,
+            data: {
+              event: e.event,
+              ...e.properties
+            }
+          }
+        ]
       };
-      return r(e, i);
+      return t.debug && console.warn("DotAnalytics: Track event to send (fallback):", n), c(n, t);
     },
     /**
      * Check if the plugin is loaded
      */
-    loaded: () => n
+    loaded: () => r
   };
 };
 export {
-  s as dotAnalytics
+  p as dotAnalytics
 };

package/lib/dotAnalytics/plugin/enricher/dot-analytics.enricher.plugin.d.ts

@@ -0,0 +1,45 @@
+import { DotCMSAnalyticsPayload } from '../../shared/dot-content-analytics.model';
+
+/**
+ * Plugin that enriches the analytics payload data based on the event type.
+ * Uses Analytics.js lifecycle events to inject context before processing.
+ * The identity plugin runs FIRST to inject context: { session_id, site_key, user_id }
+ * This enricher plugin runs SECOND to add page/device/utm data.
+ *
+ * OPTIMIZED: Uses existing payload.properties data to avoid duplication
+ */
+export declare const dotAnalyticsEnricherPlugin: () => {
+    name: string;
+    /**
+     * PAGE VIEW ENRICHMENT - Runs after identity context injection
+     * Uses optimized enrichment that leverages analytics.js payload data
+     */
+    'page:dot-analytics': ({ payload }: {
+        payload: DotCMSAnalyticsPayload;
+    }) => {
+        local_time: string;
+        utm?: import('../../shared/dot-content-analytics.model').DotCMSUtmData | undefined;
+        page: import('../../shared/dot-content-analytics.model').DotCMSPageData;
+        device: import('../../shared/dot-content-analytics.model').DotCMSDeviceData;
+        event: string;
+        properties: Record<string, unknown>;
+        options: Record<string, unknown>;
+        context?: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext | undefined;
+    };
+    /**
+     * TRACK EVENT ENRICHMENT - Runs after identity context injection
+     * Creates structured track events with pre-injected context
+     */
+    'track:dot-analytics': ({ payload }: {
+        payload: DotCMSAnalyticsPayload;
+    }) => {
+        events: {
+            event_type: "track";
+            local_time: string;
+            data: {
+                src: string;
+                event: string;
+            };
+        }[];
+    };
+};

package/lib/dotAnalytics/plugin/enricher/dot-analytics.enricher.plugin.js

@@ -0,0 +1,34 @@
+import { ANALYTICS_SOURCE_TYPE as n, EVENT_TYPES as r } from "../../shared/dot-content-analytics.constants.js";
+import { getLocalTime as a, enrichPagePayloadOptimized as i } from "../../shared/dot-content-analytics.utils.js";
+const l = () => ({
+  name: "enrich-dot-analytics",
+  /**
+   * PAGE VIEW ENRICHMENT - Runs after identity context injection
+   * Uses optimized enrichment that leverages analytics.js payload data
+   */
+  "page:dot-analytics": ({ payload: e }) => i(e),
+  // TODO: Fix this when we haver the final design for the track event
+  /**
+   * TRACK EVENT ENRICHMENT - Runs after identity context injection
+   * Creates structured track events with pre-injected context
+   */
+  "track:dot-analytics": ({ payload: e }) => {
+    const t = a();
+    return {
+      events: [
+        {
+          event_type: r.TRACK,
+          local_time: t,
+          data: {
+            event: e.event,
+            ...e.properties,
+            src: n
+          }
+        }
+      ]
+    };
+  }
+});
+export {
+  l as dotAnalyticsEnricherPlugin
+};