@dotcms/analytics 1.2.0-next.10 → 1.2.0-next.11

package/README.md

@@ -79,6 +79,67 @@ pageView(customData?: Record<string, unknown>): void
 -   **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.
 
+### Conversion Tracking
+
+The `conversion()` method tracks user conversions (purchases, downloads, sign-ups, etc.) from your application.
+
+**⚠️ IMPORTANT: Conversion events are business events that should only be tracked after a successful action or completed goal.** Tracking conversions on clicks or attempts (before success) diminishes their value as conversion metrics. Only track conversions when:
+
+-   ✅ Purchase is completed and payment is confirmed
+-   ✅ Download is successfully completed
+-   ✅ Sign-up form is submitted and account is created
+-   ✅ Form submission is successful and data is saved
+-   ✅ Any business goal is actually achieved
+
+**Method signature:**
+
+```typescript
+conversion(name: string): void
+conversion(name: string, options?: Record<string, unknown>): void
+```
+
+**Usage examples:**
+
+```typescript
+// Basic conversion tracking (after successful download)
+analytics.conversion('download');
+
+// Conversion with custom metadata (after successful purchase)
+analytics.conversion('purchase', {
+    value: 99.99,
+    currency: 'USD',
+    category: 'ecommerce',
+    productId: 'SKU-12345'
+});
+
+// Conversion with additional context (after successful signup)
+analytics.conversion('signup', {
+    source: 'homepage',
+    plan: 'premium'
+});
+```
+
+**Event payload structure:**
+
+```json
+{
+    "event_type": "conversion",
+    "local_time": "2025-10-01T16:08:33-04:00",
+    "data": {
+        "conversion": { "name": "download" },
+        "page": { "url": "...", "title": "..." },
+        "custom": { "value": 99.99, "currency": "USD", "source": "homepage" }
+    }
+}
+```
+
+**Important:**
+
+-   `name` is required and identifies the conversion type
+-   All properties in `options` go into the `custom` object
+-   Page data (url, title) is automatically added by the SDK
+-   **Only track conversions after successful completion of business goals**
+
 ### Custom Events
 
 The `track()` method allows you to track any custom user action with a unique event name and optional properties.
@@ -91,7 +152,7 @@ track(eventName: string, properties?: Record<string, unknown>): void
 
 **Important:**
 
--   `eventName` cannot be `"pageview"` (reserved for page view tracking)
+-   `eventName` cannot be `"pageview"` or `"conversion"` (reserved for specific tracking methods)
 -   `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
 
@@ -487,10 +548,18 @@ interface DotCMSAnalytics {
 
     /**
      * Track a custom event
-     * @param eventName - Name of the custom event (cannot be "pageview")
+     * @param eventName - Name of the custom event (cannot be "pageview" or "conversion")
      * @param properties - Optional object with event-specific properties
      */
     track: (eventName: string, properties?: Record<string, unknown>) => void;
+
+    /**
+     * Track a conversion event (purchase, download, sign-up, etc.)
+     * ⚠️ IMPORTANT: Only track conversions after successful completion of business goals
+     * @param name - Name of the conversion (e.g., "purchase", "download", "signup")
+     * @param options - Optional object with conversion metadata (all properties go into custom object)
+     */
+    conversion: (name: string, options?: Record<string, unknown>) => void;
 }
 ```
 
@@ -580,6 +649,52 @@ When you call `track(eventName, properties)`, the following structure is sent:
 }
 ```
 
+### Conversion Event Structure
+
+When you call `conversion(name, options)`, 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: "conversion",
+        local_time: string,    // ISO 8601 timestamp
+        data: {
+            conversion: {      // 🤖 AUTOMATIC - Conversion Info
+                name: string;  //    Your conversion name
+            },
+            page: {            // 🤖 AUTOMATIC - Page Information
+                url: string;   //    Full URL
+                title: string; //    Page title
+            },
+            custom?: {         // 👤 YOUR DATA (optional)
+                // All properties from options parameter
+                value?: number;
+                currency?: string;
+                category?: string;
+                // ... any other custom properties
+            }
+        }
+    }]
+}
+```
+
+**Key Points:**
+
+-   🤖 Conversion name and page data are captured **automatically**
+-   👤 All properties in `options` go into the `custom` object
+-   ⚠️ **Only track conversions after successful completion of business goals**
+
 ## Under the Hood
 
 ### Storage Keys

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

@@ -1,63 +1,84 @@
-import { Analytics as c } from "analytics";
-import { ANALYTICS_WINDOWS_ACTIVE_KEY as r, ANALYTICS_WINDOWS_CLEANUP_KEY as l } from "../../uve/src/internal/constants.js";
-import { dotAnalyticsClickPlugin as d } from "./plugin/click/dot-analytics.click.plugin.js";
+import { Analytics as l } from "analytics";
+import { ANALYTICS_WINDOWS_ACTIVE_KEY as a, ANALYTICS_WINDOWS_CLEANUP_KEY as d } from "../../uve/src/internal/constants.js";
+import { dotAnalyticsClickPlugin as y } from "./plugin/click/dot-analytics.click.plugin.js";
 import { dotAnalyticsEnricherPlugin as m } from "./plugin/enricher/dot-analytics.enricher.plugin.js";
 import { dotAnalyticsIdentityPlugin as u } from "./plugin/identity/dot-analytics.identity.plugin.js";
 import { dotAnalyticsImpressionPlugin as p } from "./plugin/impression/dot-analytics.impression.plugin.js";
-import { dotAnalytics as y } from "./plugin/main/dot-analytics.plugin.js";
-import { validateAnalyticsConfig as A, getEnhancedTrackingPlugins as f } from "./shared/utils/dot-analytics.utils.js";
-import { cleanupActivityTracking as w } from "./plugin/identity/dot-analytics.identity.activity-tracker.js";
-const v = (n) => {
-  const o = A(n);
-  if (o)
+import { dotAnalytics as A } from "./plugin/main/dot-analytics.plugin.js";
+import { DotCMSPredefinedEventType as f } from "./shared/constants/dot-analytics.constants.js";
+import { validateAnalyticsConfig as C, getEnhancedTrackingPlugins as w } from "./shared/utils/dot-analytics.utils.js";
+import { cleanupActivityTracking as g } from "./plugin/identity/dot-analytics.identity.activity-tracker.js";
+const _ = (t) => {
+  const e = C(t);
+  if (e)
     return console.error(
-      `DotCMS Analytics [Core]: Missing ${o.join(" and ")} in configuration`
-    ), typeof window < "u" && (window[r] = !1), null;
-  const a = f(
-    n,
+      `DotCMS Analytics [Core]: Missing ${e.join(" and ")} in configuration`
+    ), typeof window < "u" && (window[a] = !1), null;
+  const s = w(
+    t,
     p,
-    d
-  ), i = c({
+    y
+  ), i = l({
     app: "dotAnalytics",
-    debug: n.debug,
+    debug: t.debug,
     plugins: [
-      u(n),
+      u(t),
       // Inject identity context
-      ...a,
+      ...s,
       //Track content impressions & clicks (conditionally loaded)
       m(),
       // Enrich and clean payload with page, device, utm data and custom data
-      y(n)
+      A(t)
       // Send events to server
     ]
-  }), e = () => w();
-  return typeof window < "u" && (window.addEventListener("beforeunload", e), window[l] = e, window[r] = !0, window.dispatchEvent(new CustomEvent("dotcms:analytics:ready"))), {
+  }), r = () => g();
+  return typeof window < "u" && (window.addEventListener("beforeunload", r), window[d] = r, window[a] = !0, window.dispatchEvent(new CustomEvent("dotcms:analytics:ready"))), {
     /**
      * Track a page view.
      * 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: (t = {}) => {
+    pageView: (n = {}) => {
       if (!i) {
         console.warn("DotCMS Analytics [Core]: Analytics instance not initialized");
         return;
       }
-      i.page(t);
+      i.page(n);
     },
     /**
      * Track a custom event.
      * @param eventName - The name of the event to track
      * @param payload - Custom data to include with the event (any valid JSON object)
      */
-    track: (t, s = {}) => {
+    track: (n, o = {}) => {
       if (!i) {
         console.warn("DotCMS Analytics [Core]: Analytics instance not initialized");
         return;
       }
-      i.track(t, s);
+      i.track(n, o);
+    },
+    /**
+     * Track a conversion event.
+     * @param name - Name of the conversion (e.g., 'purchase', 'download', 'signup')
+     * @param options - Optional custom data
+     */
+    conversion: (n, o = {}) => {
+      if (!i) {
+        console.warn("DotCMS Analytics [Core]: Analytics instance not initialized");
+        return;
+      }
+      if (!n || n.trim() === "") {
+        console.warn("DotCMS Analytics [Core]: Conversion name cannot be empty");
+        return;
+      }
+      const c = {
+        name: n,
+        ...Object.keys(o).length > 0 && { custom: o }
+      };
+      i.track(f.CONVERSION, c);
     }
   };
 };
 export {
-  v as initializeContentAnalytics
+  _ as initializeContentAnalytics
 };

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

@@ -1,4 +1,4 @@
-import { DotCMSPredefinedEventType as n } from "../../shared/constants/dot-analytics.constants.js";
+import { DotCMSPredefinedEventType as r } from "../../shared/constants/dot-analytics.constants.js";
 import { getLocalTime as i, enrichPagePayloadOptimized as o } from "../../shared/utils/dot-analytics.utils.js";
 const l = () => ({
   name: "enrich-dot-analytics",
@@ -8,12 +8,12 @@ const l = () => ({
    * @returns {EnrichedAnalyticsPayload} Enriched payload ready for event creation
    */
   "page:dot-analytics": ({
-    payload: t
+    payload: e
   }) => {
-    const e = o(t);
-    if (!e.page)
+    const t = o(e);
+    if (!t.page)
       throw new Error("DotCMS Analytics: Missing required page data");
-    return e;
+    return t;
   },
   /**
    * TRACK EVENT ENRICHMENT - Runs after identity context injection
@@ -23,19 +23,19 @@ const l = () => ({
    * @returns {EnrichedTrackPayload} Enriched payload ready for event structuring
    */
   "track:dot-analytics": ({
-    payload: t
+    payload: e
   }) => {
-    const { event: e } = t, r = i();
-    return e === n.CONTENT_IMPRESSION || e === n.CONTENT_CLICK ? {
-      ...t,
+    const { event: t } = e, n = i();
+    return t === r.CONTENT_IMPRESSION || t === r.CONTENT_CLICK || t === r.CONVERSION ? {
+      ...e,
       page: {
         title: document.title,
         url: window.location.href
       },
-      local_time: r
+      local_time: n
     } : {
-      ...t,
-      local_time: r
+      ...e,
+      local_time: n
     };
   }
 });

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

@@ -2,8 +2,8 @@ import { getUVEState as m } from "../../../../uve/src/lib/core/core.utils.js";
 import "../../../../uve/src/internal/constants.js";
 import { getViewportMetrics as d, isElementMeetingVisibilityThreshold as u } from "./dot-analytics.impression.utils.js";
 import { DEFAULT_IMPRESSION_CONFIG as l, IMPRESSION_EVENT_TYPE as g } from "../../shared/constants/dot-analytics.constants.js";
-import { createPluginLogger as p, isBrowser as a, findContentlets as b, extractContentletIdentifier as c, createContentletObserver as f, extractContentletData as v } from "../../shared/utils/dot-analytics.utils.js";
-class C {
+import { createPluginLogger as p, isBrowser as a, INITIAL_SCAN_DELAY_MS as f, findContentlets as b, extractContentletIdentifier as c, createContentletObserver as v, extractContentletData as I } from "../../shared/utils/dot-analytics.utils.js";
+class E {
   constructor(e) {
     this.observer = null, this.mutationObserver = null, this.elementImpressionStates = /* @__PURE__ */ new Map(), this.sessionTrackedImpressions = /* @__PURE__ */ new Set(), this.currentPagePath = "", this.subscribers = /* @__PURE__ */ new Set(), this.logger = p("Impression", e), this.impressionConfig = this.resolveImpressionConfig(e.impressions);
   }
@@ -43,7 +43,9 @@ class C {
         this.logger.warn("Impression tracking disabled in editor mode");
         return;
       }
-      this.initializeIntersectionObserver(), this.findAndObserveContentletElements(), this.initializeDynamicContentDetector(), this.initializePageVisibilityHandler(), this.initializePageNavigationHandler(), this.logger.info("Impression tracking initialized with config:", this.impressionConfig);
+      this.initializeIntersectionObserver(), typeof window < "u" && setTimeout(() => {
+        this.logger.debug("Running initial scan after timeout..."), this.findAndObserveContentletElements();
+      }, f), this.initializeDynamicContentDetector(), this.initializePageVisibilityHandler(), this.initializePageNavigationHandler(), this.logger.info("Impression tracking initialized with config:", this.impressionConfig);
     }
   }
   /** Sets up IntersectionObserver with configured visibility threshold */
@@ -90,7 +92,7 @@ class C {
   }
   /** Watches for new contentlets added to DOM (debounced for performance) */
   initializeDynamicContentDetector() {
-    a() && (this.mutationObserver = f(() => {
+    a() && (this.mutationObserver = v(() => {
       this.findAndObserveContentletElements();
     }), this.logger.info("MutationObserver enabled for dynamic content detection"));
   }
@@ -148,7 +150,7 @@ class C {
   trackAndSendImpression(e, i) {
     const t = this.elementImpressionStates.get(e);
     if (!t) return;
-    const s = t.visibleSince ? Date.now() - t.visibleSince : 0, n = v(i), r = d(i), o = parseInt(i.dataset.dotAnalyticsDomIndex || "-1", 10), h = {
+    const s = t.visibleSince ? Date.now() - t.visibleSince : 0, n = I(i), r = d(i), o = parseInt(i.dataset.dotAnalyticsDomIndex || "-1", 10), h = {
       content: {
         identifier: n.identifier,
         inode: n.inode,
@@ -196,5 +198,5 @@ class C {
   }
 }
 export {
-  C as DotCMSImpressionTracker
+  E as DotCMSImpressionTracker
 };

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

@@ -1,21 +1,21 @@
-import { DotCMSPredefinedEventType as c } from "../../shared/constants/dot-analytics.constants.js";
-import { sendAnalyticsEvent as f } from "../../shared/http/dot-analytics.http.js";
+import { DotCMSPredefinedEventType as r } from "../../shared/constants/dot-analytics.constants.js";
+import { sendAnalyticsEvent as N } from "../../shared/http/dot-analytics.http.js";
 import { createAnalyticsQueue as w } from "../../shared/queue/dot-analytics.queue.utils.js";
-const _ = (l) => {
+const _ = (d) => {
   let u = !1;
-  const m = l.queue !== !1;
-  let d = null;
-  const y = (e) => {
-    const n = e.events[0], t = e.context;
-    m && d ? d.enqueue(n, t) : f(e, l);
+  const m = d.queue !== !1;
+  let p = null;
+  const v = (e) => {
+    const c = e.events[0], t = e.context;
+    m && p ? p.enqueue(c, t) : N(e, d);
   };
   return {
     name: "dot-analytics",
-    config: l,
+    config: d,
     /**
      * Initialize the plugin with optional queue management
      */
-    initialize: () => (u = !0, m && (d = w(l), d.initialize()), Promise.resolve()),
+    initialize: () => (u = !0, m && (p = w(d), p.initialize()), Promise.resolve()),
     /**
      * Track a page view event
      * Receives enriched payload from the enricher plugin and structures it into a pageview event
@@ -23,24 +23,24 @@ const _ = (l) => {
     page: ({ payload: e }) => {
       if (!u)
         throw new Error("DotCMS Analytics: Plugin not initialized");
-      const { context: n, page: t, utm: p, custom: i, local_time: o } = e;
+      const { context: c, page: t, utm: E, custom: s, local_time: a } = e;
       if (!t)
         throw new Error("DotCMS Analytics: Missing required page data");
-      const v = {
-        context: n,
+      const y = {
+        context: c,
         events: [
           {
-            event_type: c.PAGEVIEW,
-            local_time: o,
+            event_type: r.PAGEVIEW,
+            local_time: a,
             data: {
               page: t,
-              ...p && { utm: p },
-              ...i && { custom: i }
+              ...E && { utm: E },
+              ...s && { custom: s }
             }
           }
         ]
       };
-      y(v);
+      v(y);
     },
     /**
      * Track a custom or predefined event
@@ -53,44 +53,59 @@ const _ = (l) => {
     track: ({ payload: e }) => {
       if (!u)
         throw new Error("DotCMS Analytics: Plugin not initialized");
-      const { event: n, properties: t, context: p, local_time: i } = e;
-      let o;
-      switch (n) {
-        case c.CONTENT_IMPRESSION: {
-          const E = t, { content: s, position: a } = E, { page: r } = e;
-          if (!s || !a || !r)
+      const { event: c, properties: t, context: E, local_time: s } = e;
+      let a;
+      switch (c) {
+        case r.CONTENT_IMPRESSION: {
+          const l = t, { content: n, position: i } = l, { page: o } = e;
+          if (!n || !i || !o)
             throw new Error("DotCMS Analytics: Missing required impression data");
-          o = {
-            event_type: c.CONTENT_IMPRESSION,
-            local_time: i,
+          a = {
+            event_type: r.CONTENT_IMPRESSION,
+            local_time: s,
             data: {
-              content: s,
-              position: a,
-              page: r
+              content: n,
+              position: i,
+              page: o
             }
           };
           break;
         }
-        case c.CONTENT_CLICK: {
-          const E = t, { content: s, position: a, element: r } = E, { page: C } = e;
-          if (!s || !a || !r || !C)
+        case r.CONTENT_CLICK: {
+          const l = t, { content: n, position: i, element: o } = l, { page: C } = e;
+          if (!n || !i || !o || !C)
             throw new Error("DotCMS Analytics: Missing required click data");
-          o = {
-            event_type: c.CONTENT_CLICK,
-            local_time: i,
+          a = {
+            event_type: r.CONTENT_CLICK,
+            local_time: s,
             data: {
-              content: s,
-              position: a,
-              element: r,
+              content: n,
+              position: i,
+              element: o,
               page: C
             }
           };
           break;
         }
+        case r.CONVERSION: {
+          const l = t, { name: n, custom: i } = l, { page: o } = e;
+          if (!n || !o)
+            throw new Error("DotCMS Analytics: Missing required conversion data");
+          a = {
+            event_type: r.CONVERSION,
+            local_time: s,
+            data: {
+              conversion: { name: n },
+              page: o,
+              ...i && { custom: i }
+            }
+          };
+          break;
+        }
         default: {
-          o = {
-            event_type: n,
-            local_time: i,
+          a = {
+            event_type: c,
+            local_time: s,
             data: {
               custom: t
             }
@@ -98,9 +113,9 @@ const _ = (l) => {
           break;
         }
       }
-      y({
-        context: p,
-        events: [o]
+      v({
+        context: E,
+        events: [a]
       });
     },
     /**

package/lib/core/shared/constants/dot-analytics.constants.d.ts

@@ -9,6 +9,7 @@ export declare const DotCMSPredefinedEventType: {
     readonly PAGEVIEW: "pageview";
     readonly CONTENT_IMPRESSION: "content_impression";
     readonly CONTENT_CLICK: "content_click";
+    readonly CONVERSION: "conversion";
 };
 /**
  * Type for structured events

package/lib/core/shared/constants/dot-analytics.constants.js

@@ -1,7 +1,8 @@
 const I = "/api/v1/analytics/content/event", c = {
   PAGEVIEW: "pageview",
   CONTENT_IMPRESSION: "content_impression",
-  CONTENT_CLICK: "content_click"
+  CONTENT_CLICK: "content_click",
+  CONVERSION: "conversion"
 }, s = [
   "utm_source",
   "utm_medium",
@@ -27,13 +28,13 @@ const I = "/api/v1/analytics/content/event", c = {
   dwellMs: T,
   maxNodes: n,
   throttleMs: S
-}, U = "content_impression", M = "content_click", D = 300, a = "a, button", R = "dotcms-analytics-contentlet";
+}, U = "content_impression", M = "content_click", D = 300, R = "a, button", a = "dotcms-analytics-contentlet";
 export {
   L as ACTIVITY_EVENTS,
-  R as ANALYTICS_CONTENTLET_CLASS,
+  a as ANALYTICS_CONTENTLET_CLASS,
   I as ANALYTICS_ENDPOINT,
   i as ANALYTICS_JS_DEFAULT_PROPERTIES,
-  a as CLICKABLE_ELEMENTS_SELECTOR,
+  R as CLICKABLE_ELEMENTS_SELECTOR,
   M as CLICK_EVENT_TYPE,
   D as DEFAULT_CLICK_THROTTLE_MS,
   C as DEFAULT_IMPRESSION_CONFIG,

package/lib/core/shared/models/event.model.d.ts

@@ -50,6 +50,24 @@ export type DotCMSCustomEventData = {
     /** Custom data associated with the event (any valid JSON) */
     custom: JsonObject;
 };
+/**
+ * Element information for analytics events.
+ * Base type for element metadata in click and conversion events.
+ */
+export type DotCMSElementData = {
+    /** Text content of the element */
+    text: string;
+    /** Type of element (anchor, button, input, etc.) */
+    type: string;
+    /** Element ID (required by backend, empty string if not present) */
+    id: string;
+    /** Element classes (required by backend, empty string if not present) */
+    class: string;
+    /** Link destination as written in HTML (relative path, only for <a> elements, empty string for buttons) */
+    href: string;
+    /** Additional element attributes in key:value format (e.g., ['data-category:val', 'data-campaign:val2']) */
+    attributes: string[];
+};
 /**
  * Partial content impression data sent by producer plugins.
  * Contains only impression-specific data (content and position).
@@ -81,20 +99,17 @@ export type DotCMSContentImpressionPayload = {
  */
 export type DotCMSContentClickPayload = DotCMSContentImpressionPayload & {
     /** Clicked element information */
-    element: {
-        /** Text content of the element */
-        text: string;
-        /** Type of element (anchor, button, etc.) */
-        type: string;
-        /** Element ID (required by backend, empty string if not present) */
-        id: string;
-        /** Element classes (required by backend, empty string if not present) */
-        class: string;
-        /** Link destination as written in HTML (relative path, only for <a> elements, empty string for buttons) */
-        href: string;
-        /** Additional element attributes in key:value format (e.g., ['data-category:val', 'data-campaign:val2']) */
-        attributes: string[];
-    };
+    element: DotCMSElementData;
+};
+/**
+ * Conversion payload sent when tracking conversions.
+ * Contains conversion name and optional custom data.
+ */
+export type DotCMSConversionPayload = {
+    /** Name of the conversion event */
+    name: string;
+    /** Optional custom user data (any valid JSON) */
+    custom?: JsonObject;
 };
 /**
  * Complete data structure for content impression events after enrichment.
@@ -112,6 +127,21 @@ export type DotCMSContentClickEventData = DotCMSContentClickPayload & {
     /** Minimal page data where the click occurred (added by enricher) */
     page: DotCMSContentImpressionPageData;
 };
+/**
+ * Complete data structure for conversion events after enrichment.
+ * Includes page data added by the enricher plugin.
+ */
+export type DotCMSConversionEventData = {
+    /** Conversion information */
+    conversion: {
+        /** Name of the user-defined conversion */
+        name: string;
+    };
+    /** Page data where the conversion occurred (added by enricher) */
+    page: DotCMSContentImpressionPageData;
+    /** Optional custom user data (any valid JSON) */
+    custom?: JsonObject;
+};
 /**
  * Pageview event structure.
  */
@@ -124,6 +154,10 @@ export type DotCMSContentImpressionEvent = DotCMSEventBase<typeof DotCMSPredefin
  * Content click event structure.
  */
 export type DotCMSContentClickEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.CONTENT_CLICK, DotCMSContentClickEventData>;
+/**
+ * Conversion event structure.
+ */
+export type DotCMSConversionEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.CONVERSION, DotCMSConversionEventData>;
 /**
  * Custom event structure.
  */
@@ -132,4 +166,4 @@ export type DotCMSCustomEvent = DotCMSEventBase<DotCMSCustomEventType, DotCMSCus
  * Union type for all possible analytics events.
  * Used primarily for type documentation and validation.
  */
-export type DotCMSEvent = DotCMSPageViewEvent | DotCMSContentImpressionEvent | DotCMSContentClickEvent | DotCMSCustomEvent;
+export type DotCMSEvent = DotCMSPageViewEvent | DotCMSContentImpressionEvent | DotCMSContentClickEvent | DotCMSConversionEvent | DotCMSCustomEvent;

package/lib/core/shared/models/library.model.d.ts

@@ -45,20 +45,29 @@ export interface ViewportMetrics {
 }
 /**
  * Main interface for the DotCMS Analytics SDK.
- * Provides the core methods for tracking page views and custom events.
+ * Provides the core methods for tracking page views, custom events, and conversions.
  */
 export interface DotCMSAnalytics {
     /**
      * Track a page view event.
      * @param payload - Optional custom data to include with the page view (any valid JSON object)
      */
-    pageView: (payload?: JsonObject) => void;
+    pageView(): void;
+    pageView(payload: JsonObject): void;
     /**
      * Track a custom event.
      * @param eventName - The name/type of the event to track
      * @param payload - Custom data to include with the event (any valid JSON object)
      */
-    track: (eventName: string, payload: JsonObject) => void;
+    track(eventName: string): void;
+    track(eventName: string, payload: JsonObject): void;
+    /**
+     * Track a conversion event.
+     * @param name - Name of the conversion (e.g., 'purchase', 'download', 'signup')
+     * @param options - Optional custom data and element information
+     */
+    conversion(name: string): void;
+    conversion(name: string, options: JsonObject): void;
 }
 /**
  * Configuration interface for DotCMS Analytics SDK.

package/lib/react/hook/useContentAnalytics.js

@@ -1,27 +1,33 @@
-import { useMemo as n, useCallback as o } from "react";
-import { getUVEState as u } from "../../../uve/src/lib/core/core.utils.js";
+import { useMemo as s, useCallback as o } from "react";
+import { getUVEState as l } from "../../../uve/src/lib/core/core.utils.js";
 import "../../../uve/src/internal/constants.js";
-import { initializeAnalytics as l } from "../internal/utils.js";
-const h = (r) => {
-  const t = n(() => l(r), [r.server, r.siteAuth]), e = n(() => !!u(), []);
+import { initializeAnalytics as m } from "../internal/utils.js";
+const h = (i) => {
+  const t = s(() => m(i), [i.server, i.siteAuth]), e = s(() => !!l(), []);
   if (!t)
     throw new Error(
       "DotCMS Analytics: Failed to initialize. Please verify the required configuration (server and siteAuth)."
     );
   const a = o(
-    (i, c = {}) => {
-      e || t.track(i, c);
+    (r, n = {}) => {
+      e || t.track(r, n);
     },
     [t, e]
-  ), s = o(
-    (i = {}) => {
-      e || t.pageView(i);
+  ), c = o(
+    (r = {}) => {
+      e || t.pageView(r);
+    },
+    [t, e]
+  ), u = o(
+    (r, n = {}) => {
+      e || t.conversion(r, n);
     },
     [t, e]
   );
   return {
     track: a,
-    pageView: s
+    pageView: c,
+    conversion: u
   };
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/analytics",
-  "version": "1.2.0-next.10",
+  "version": "1.2.0-next.11",
   "description": "Official JavaScript library for Content Analytics with DotCMS.",
   "repository": {
     "type": "git",