@dotcms/analytics 1.1.1-next.2 → 1.1.1-next.4

package/README.md

@@ -32,7 +32,7 @@ const analytics = initializeContentAnalytics({
 analytics.track('page-loaded');
 ```
 
-### React
+### React (In Development)
 
 ```bash
 npm install @dotcms/analytics
@@ -52,16 +52,48 @@ export function AppRoot() {
 }
 ```
 
+> **Note:** React API is subject to change during development.
+
 ## 📘 Core Concepts
 
-### Events
+### Page Views
 
-Track any user action as an event using `track('event-name', { payload })`.
+The `pageView()` method tracks page navigation events. **It automatically enriches the event with comprehensive data**, including:
 
-### Page Views
+-   **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
+
+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
+
+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:**
 
--   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()`.
+-   `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,25 +108,64 @@ Track any user action as an event using `track('event-name', { payload })`.
 
 ## ⚙️ Configuration Options
 
-| Option         | Type      | Required | Default                             | Description                            |
+<<<<<<< HEAD
+| Option | Type | Required | Default | Description |
 | -------------- | --------- | -------- | ----------------------------------- | -------------------------------------- |
-| `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 |
+| `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 |
 
 ## 🛠️ 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
@@ -105,77 +176,167 @@ const analytics = initializeContentAnalytics({
     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({
-    siteAuth: 'SITE_AUTH',
-    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({
-    siteAuth: 'SITE_AUTH',
-    server: 'https://demo.dotcms.com'
-});
-useEffect(() => {
-    pageView();
-}, []);
-```
-
-**Advanced: Manual Tracking with Router**
+function MyComponent() {
+    const { track, pageView } = useContentAnalytics({
+        siteAuth: 'SITE_AUTH',
+        server: 'https://demo.dotcms.com'
+    });
 
-```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({
-    siteAuth: 'SITE_AUTH',
-    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;
 }
 ```
 
-**Enriched AnalyticsEvent includes:**
+### Page View Event Structure
 
--   `context`: siteKey, sessionId, userId
--   `page`: URL, title, referrer, path
--   `device`: screen size, language, viewport
--   `utm`: source, medium, campaign, term, etc.
+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
+            }
+        }
+    }]
+}
+```
+
+**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`
+
+### 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
 
@@ -215,23 +376,23 @@ Standalone attributes to verify:
 
 ## dotCMS 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.
+-   **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
 
-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`)

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

@@ -1,4 +1,4 @@
-import { DotCMSAnalytics, DotCMSAnalyticsConfig } from './shared/dot-content-analytics.model';
+import { DotCMSAnalytics, DotCMSAnalyticsConfig } from './shared/models';
 /**
  * Creates an analytics instance for content analytics tracking.
  *

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

@@ -1,40 +1,42 @@
-import { Analytics as s } from "analytics";
-import { dotAnalytics as l } from "./plugin/dot-analytics.plugin.js";
-import { dotAnalyticsEnricherPlugin as u } from "./plugin/enricher/dot-analytics.enricher.plugin.js";
-import { dotAnalyticsIdentityPlugin as a } 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.siteAuth)
-    return console.error('DotContentAnalytics: Missing "siteAuth" in configuration'), null;
-  if (!n.server)
-    return console.error('DotContentAnalytics: Missing "server" in configuration'), null;
-  const t = s({
+import { Analytics as o } from "analytics";
+import { dotAnalytics as s } from "./plugin/dot-analytics.plugin.js";
+import { dotAnalyticsEnricherPlugin as l } from "./plugin/enricher/dot-analytics.enricher.plugin.js";
+import { dotAnalyticsIdentityPlugin as u } from "./plugin/identity/dot-analytics.identity.plugin.js";
+import { cleanupActivityTracking as a } from "./shared/dot-content-analytics.activity-tracker.js";
+const f = (i) => {
+  if (!i.siteAuth)
+    return console.error('DotCMS Analytics: Missing "siteAuth" in configuration'), null;
+  if (!i.server)
+    return console.error('DotCMS Analytics: Missing "server" in configuration'), null;
+  const t = o({
     app: "dotAnalytics",
-    debug: n.debug,
+    debug: i.debug,
     plugins: [
-      a(n),
+      u(i),
       // Inject identity context (user_id, session_id, local_tz)
-      u(),
-      // Enrich with page, device, utm data
-      l(n)
+      l(),
+      // Enrich and clean payload with page, device, utm data and custom data
+      s(i)
       // Send events to server
     ]
-  }), e = () => c();
-  return typeof window < "u" && (window.addEventListener("beforeunload", e), window.__dotAnalyticsCleanup = e), {
+  }), r = () => a();
+  return typeof window < "u" && (window.addEventListener("beforeunload", r), window.__dotAnalyticsCleanup = r), {
     /**
      * 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: (n = {}) => {
+      t == null || t.page(n);
     },
     /**
      * 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: (n, e = {}) => {
+      t == null || t.track(n, e);
     }
   };
 };

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

@@ -1,4 +1,4 @@
-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,
@@ -17,12 +17,12 @@ export declare const dotAnalytics: (config: DotCMSAnalyticsConfig) => {
     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>;
     /**
      * 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>;
     /**

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

@@ -1,79 +1,47 @@
-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;
+import { sendAnalyticsEventToServer as r } from "../shared/dot-content-analytics.http.js";
+const s = (a) => {
+  let n = !1;
   return {
     name: "dot-analytics",
-    config: v,
+    config: a,
     /**
      * Initialize the plugin
      */
-    initialize: () => (r = !0, Promise.resolve()),
+    initialize: () => (n = !0, Promise.resolve()),
     /**
      * 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: (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");
-      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 }
-            }
-          }
-        ]
+    page: (e) => {
+      const { config: o, payload: t } = e;
+      if (!n)
+        throw new Error("DotCMS Analytics: Plugin not initialized");
+      const i = {
+        context: t.context,
+        events: t.events
       };
-      return t.debug && console.warn("DotAnalytics: Pageview event to send:", d), c(d, t);
+      return r(i, o);
     },
-    // 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
+     * The enricher plugin has already built the complete request body
      */
-    track: (a) => {
-      const { config: t, payload: e } = a;
-      if (!r)
-        throw new Error("DotAnalytics: Plugin not initialized");
-      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
-            }
-          }
-        ]
+    track: (e) => {
+      const { config: o, payload: t } = e;
+      if (!n)
+        throw new Error("DotCMS Analytics: Plugin not initialized");
+      const i = {
+        context: t.context,
+        events: t.events
       };
-      return t.debug && console.warn("DotAnalytics: Track event to send (fallback):", n), c(n, t);
+      return r(i, o);
     },
     /**
      * Check if the plugin is loaded
      */
-    loaded: () => r
+    loaded: () => n
   };
 };
 export {
-  p as dotAnalytics
+  s as dotAnalytics
 };

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

@@ -1,44 +1,28 @@
-import { DotCMSAnalyticsPayload } from '../../shared/dot-content-analytics.model';
+import { AnalyticsBasePayloadWithContext, AnalyticsTrackPayloadWithContext, DotCMSAnalyticsRequestBody } from '../../shared/models';
 /**
  * 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_auth, user_id }
- * This enricher plugin runs SECOND to add page/device/utm data.
+ * The identity plugin runs FIRST to inject context: { session_id, site_auth, user_id, device }
+ * This enricher plugin runs SECOND to add page/utm/custom data.
  *
- * OPTIMIZED: Uses existing payload.properties data to avoid duplication
+ * Returns the final request body structure ready to send to the server.
  */
 export declare const dotAnalyticsEnricherPlugin: () => {
     name: string;
     /**
      * PAGE VIEW ENRICHMENT - Runs after identity context injection
-     * Uses optimized enrichment that leverages analytics.js payload data
+     * Returns the complete request body for pageview events
+     * @returns {DotCMSAnalyticsRequestBody} Complete request body ready to send
      */
     'page:dot-analytics': ({ payload }: {
-        payload: DotCMSAnalyticsPayload;
-    }) => {
-        local_time: string;
-        utm?: import('../../shared/dot-content-analytics.model').DotCMSUtmData;
-        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;
-    };
+        payload: AnalyticsBasePayloadWithContext;
+    }) => DotCMSAnalyticsRequestBody;
     /**
      * TRACK EVENT ENRICHMENT - Runs after identity context injection
-     * Creates structured track events with pre-injected context
+     * Returns the complete request body for custom events
+     * @returns {DotCMSAnalyticsRequestBody} Complete request body ready to send
      */
     'track:dot-analytics': ({ payload }: {
-        payload: DotCMSAnalyticsPayload;
-    }) => {
-        events: {
-            event_type: "track";
-            local_time: string;
-            data: {
-                src: string;
-                event: string;
-            };
-        }[];
-    };
+        payload: AnalyticsTrackPayloadWithContext;
+    }) => DotCMSAnalyticsRequestBody;
 };