@dotcms/analytics 1.1.1 → 1.2.0-next.10

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

@@ -0,0 +1,63 @@
+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 { 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)
+    return console.error(
+      `DotCMS Analytics [Core]: Missing ${o.join(" and ")} in configuration`
+    ), typeof window < "u" && (window[r] = !1), null;
+  const a = f(
+    n,
+    p,
+    d
+  ), i = c({
+    app: "dotAnalytics",
+    debug: n.debug,
+    plugins: [
+      u(n),
+      // Inject identity context
+      ...a,
+      //Track content impressions & clicks (conditionally loaded)
+      m(),
+      // Enrich and clean payload with page, device, utm data and custom data
+      y(n)
+      // 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"))), {
+    /**
+     * 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 = {}) => {
+      if (!i) {
+        console.warn("DotCMS Analytics [Core]: Analytics instance not initialized");
+        return;
+      }
+      i.page(t);
+    },
+    /**
+     * 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 = {}) => {
+      if (!i) {
+        console.warn("DotCMS Analytics [Core]: Analytics instance not initialized");
+        return;
+      }
+      i.track(t, s);
+    }
+  };
+};
+export {
+  v as initializeContentAnalytics
+};

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

@@ -0,0 +1,108 @@
+import { DotCMSAnalyticsConfig, DotCMSContentClickPayload } from '../../shared/models';
+/** Callback function for click events */
+export type ClickCallback = (eventName: string, payload: DotCMSContentClickPayload) => void;
+/** Subscription object with unsubscribe method */
+export interface ClickSubscription {
+    unsubscribe: () => void;
+}
+/**
+ * Tracks content clicks using event listeners on contentlet containers.
+ * Detects clicks on <a> and <button> elements inside contentlets and fires events.
+ *
+ * Features:
+ * - Attaches event listeners to contentlet containers
+ * - Tracks clicks on anchor and button elements only
+ * - Uses MutationObserver to detect dynamically added content
+ * - Throttles rapid clicks to prevent duplicates (300ms)
+ * - Subscription-based event system for decoupling
+ *
+ * @example
+ * ```typescript
+ * const tracker = new DotCMSClickTracker(config);
+ * const subscription = tracker.onClick((eventName, payload) => {
+ *   console.log('Click detected:', payload);
+ * });
+ * tracker.initialize();
+ * // Later: subscription.unsubscribe();
+ * ```
+ */
+export declare class DotCMSClickTracker {
+    private config;
+    private mutationObserver;
+    private lastClickTime;
+    private logger;
+    private subscribers;
+    private trackedElements;
+    private elementHandlers;
+    constructor(config: DotCMSAnalyticsConfig);
+    /**
+     * Subscribe to click events
+     * @param callback - Function called when click is detected
+     * @returns Subscription object with unsubscribe method
+     */
+    onClick(callback: ClickCallback): ClickSubscription;
+    /**
+     * Notifies all subscribers of a click event
+     * @param eventName - Name of the event (e.g., 'content_click')
+     * @param payload - Click event payload with content and element data
+     */
+    private notifySubscribers;
+    /**
+     * Initialize click tracking system
+     *
+     * Performs the following:
+     * - Validates browser environment
+     * - Scans for existing contentlets after a delay (100ms)
+     * - Sets up MutationObserver for dynamic content
+     *
+     * The delay allows React/Next.js to finish initial rendering
+     * before attaching listeners.
+     */
+    initialize(): void;
+    /**
+     * Attach click listener to a contentlet container
+     *
+     * Skips if element already has a listener attached.
+     * The listener delegates to handleContentletClick which:
+     * - Finds clicked anchor/button elements
+     * - Extracts contentlet and element data
+     * - Applies throttling (300ms)
+     * - Notifies subscribers
+     *
+     * @param element - Contentlet container element to track
+     */
+    private attachClickListener;
+    /**
+     * Find and attach listeners to all contentlet elements in the DOM
+     *
+     * Scans the entire document for elements with the
+     * `.dotcms-analytics-contentlet` class and attaches click
+     * listeners if not already tracked.
+     *
+     * Called during initialization and whenever DOM mutations are detected.
+     */
+    private findAndAttachListeners;
+    /**
+     * Initialize MutationObserver to detect new contentlet containers
+     * Uses same simple strategy as impression tracker - no complex filtering
+     */
+    private initializeMutationObserver;
+    /**
+     * Remove all click listeners from tracked contentlets
+     *
+     * Iterates through all contentlet elements and removes their
+     * click event handlers, cleaning up WeakMap references.
+     */
+    private removeAllListeners;
+    /**
+     * Cleanup all resources used by the click tracker
+     *
+     * Performs:
+     * - Removes all event listeners from contentlets
+     * - Disconnects MutationObserver
+     * - Clears internal references
+     *
+     * Should be called when the plugin is disabled or on page unload.
+     */
+    cleanup(): void;
+}

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

@@ -0,0 +1,144 @@
+import { handleContentletClick as c } from "./dot-analytics.click.utils.js";
+import { DEFAULT_CLICK_THROTTLE_MS as d } from "../../shared/constants/dot-analytics.constants.js";
+import { createPluginLogger as h, isBrowser as l, INITIAL_SCAN_DELAY_MS as g, findContentlets as r, createContentletObserver as u } from "../../shared/utils/dot-analytics.utils.js";
+class C {
+  constructor(t) {
+    this.config = t, this.mutationObserver = null, this.lastClickTime = { value: 0 }, this.subscribers = /* @__PURE__ */ new Set(), this.trackedElements = /* @__PURE__ */ new WeakSet(), this.elementHandlers = /* @__PURE__ */ new WeakMap(), this.logger = h("Click", t);
+  }
+  /**
+   * Subscribe to click events
+   * @param callback - Function called when click is detected
+   * @returns Subscription object with unsubscribe method
+   */
+  onClick(t) {
+    return this.subscribers.add(t), {
+      unsubscribe: () => {
+        this.subscribers.delete(t);
+      }
+    };
+  }
+  /**
+   * Notifies all subscribers of a click event
+   * @param eventName - Name of the event (e.g., 'content_click')
+   * @param payload - Click event payload with content and element data
+   */
+  notifySubscribers(t, e) {
+    this.subscribers.forEach((i) => i(t, e));
+  }
+  /**
+   * Initialize click tracking system
+   *
+   * Performs the following:
+   * - Validates browser environment
+   * - Scans for existing contentlets after a delay (100ms)
+   * - Sets up MutationObserver for dynamic content
+   *
+   * The delay allows React/Next.js to finish initial rendering
+   * before attaching listeners.
+   */
+  initialize() {
+    if (!l()) {
+      this.logger.warn("No document, skipping");
+      return;
+    }
+    this.logger.debug("Plugin initializing"), typeof window < "u" && setTimeout(() => {
+      this.logger.debug("Running initial scan after timeout..."), this.findAndAttachListeners();
+    }, g), this.initializeMutationObserver(), this.logger.info("Plugin initialized");
+  }
+  /**
+   * Attach click listener to a contentlet container
+   *
+   * Skips if element already has a listener attached.
+   * The listener delegates to handleContentletClick which:
+   * - Finds clicked anchor/button elements
+   * - Extracts contentlet and element data
+   * - Applies throttling (300ms)
+   * - Notifies subscribers
+   *
+   * @param element - Contentlet container element to track
+   */
+  attachClickListener(t) {
+    if (this.trackedElements.has(t)) {
+      const n = t.dataset.dotAnalyticsIdentifier || "unknown";
+      this.logger.debug(`Element ${n} already has listener, skipping`);
+      return;
+    }
+    if (!t.dataset.dotAnalyticsDomIndex) {
+      const n = r();
+      t.dataset.dotAnalyticsDomIndex = String(n.indexOf(t));
+    }
+    const e = (n) => {
+      this.logger.debug("Click handler triggered on contentlet"), c(
+        n,
+        t,
+        (a, s) => {
+          const o = Date.now();
+          o - this.lastClickTime.value < d || (this.lastClickTime.value = o, this.notifySubscribers(a, s), this.logger.info(
+            `Fired click event for ${s.content.identifier}`,
+            s
+          ));
+        },
+        this.logger
+      );
+    };
+    t.addEventListener("click", e), this.trackedElements.add(t), this.elementHandlers.set(t, e);
+    const i = t.dataset.dotAnalyticsIdentifier || "unknown";
+    this.logger.log(`Attached listener to contentlet ${i}`, t);
+  }
+  /**
+   * Find and attach listeners to all contentlet elements in the DOM
+   *
+   * Scans the entire document for elements with the
+   * `.dotcms-analytics-contentlet` class and attaches click
+   * listeners if not already tracked.
+   *
+   * Called during initialization and whenever DOM mutations are detected.
+   */
+  findAndAttachListeners() {
+    this.logger.debug("findAndAttachListeners called");
+    const t = r();
+    this.logger.debug(`Scanning... found ${t.length} contentlets`);
+    let e = 0;
+    t.forEach((i) => {
+      const n = !this.trackedElements.has(i);
+      this.attachClickListener(i), n && this.trackedElements.has(i) && e++;
+    }), e > 0 && this.logger.info(`Attached ${e} new click listeners`);
+  }
+  /**
+   * Initialize MutationObserver to detect new contentlet containers
+   * Uses same simple strategy as impression tracker - no complex filtering
+   */
+  initializeMutationObserver() {
+    l() && (this.mutationObserver = u(() => {
+      this.findAndAttachListeners();
+    }), this.logger.info("MutationObserver enabled for click tracking"));
+  }
+  /**
+   * Remove all click listeners from tracked contentlets
+   *
+   * Iterates through all contentlet elements and removes their
+   * click event handlers, cleaning up WeakMap references.
+   */
+  removeAllListeners() {
+    r().forEach((e) => {
+      const i = this.elementHandlers.get(e);
+      i && (e.removeEventListener("click", i), this.elementHandlers.delete(e));
+    });
+  }
+  /**
+   * Cleanup all resources used by the click tracker
+   *
+   * Performs:
+   * - Removes all event listeners from contentlets
+   * - Disconnects MutationObserver
+   * - Clears internal references
+   *
+   * Should be called when the plugin is disabled or on page unload.
+   */
+  cleanup() {
+    this.removeAllListeners(), this.mutationObserver && (this.mutationObserver.disconnect(), this.mutationObserver = null), this.logger.info("Click tracking cleaned up");
+  }
+}
+export {
+  C as DotCMSClickTracker
+};

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

@@ -0,0 +1,36 @@
+import { AnalyticsInstance } from 'analytics';
+import { DotCMSAnalyticsConfig } from '../../shared/models';
+/**
+ * Click Plugin for DotAnalytics
+ * Handles automatic tracking of clicks on content elements.
+ *
+ * This plugin initializes the click tracker which:
+ * - Uses MutationObserver to detect contentlet containers
+ * - Attaches click listeners to each .dotcms-analytics-contentlet element
+ * - Filters for clicks on <a> or <button> elements inside tracked contentlets
+ * - Extracts contentlet data and element metadata
+ * - Throttles clicks to prevent duplicates
+ * - Fires 'content_click' events via subscription callback
+ *
+ * Note: This plugin is only registered if config.clicks is enabled.
+ * See getEnhancedTrackingPlugins() for conditional loading logic.
+ *
+ * @param {DotCMSAnalyticsConfig} config - Configuration with clicks settings
+ * @returns {Object} Plugin object with lifecycle methods
+ */
+export declare const dotAnalyticsClickPlugin: (config: DotCMSAnalyticsConfig) => {
+    name: string;
+    /**
+     * Initialize click tracking
+     * Called when Analytics.js initializes the plugin with instance context
+     * @param instance - Analytics.js instance with track method
+     */
+    initialize: ({ instance }: {
+        instance: AnalyticsInstance;
+    }) => Promise<void>;
+    /**
+     * Setup cleanup handlers when plugin is loaded
+     * Called after Analytics.js completes plugin loading
+     */
+    loaded: () => boolean;
+};

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

@@ -0,0 +1,27 @@
+import { DotCMSClickTracker as o } from "./dot-analytics.click-tracker.js";
+import { createPluginLogger as u, isBrowser as a, setupPluginCleanup as s } from "../../shared/utils/dot-analytics.utils.js";
+const g = (n) => {
+  let i = null, l = null;
+  const e = u("Click", n);
+  return {
+    name: "dot-analytics-click",
+    /**
+     * Initialize click tracking
+     * Called when Analytics.js initializes the plugin with instance context
+     * @param instance - Analytics.js instance with track method
+     */
+    initialize: ({ instance: r }) => (i = new o(n), l = i.onClick((c, t) => {
+      r.track(c, t);
+    }), i.initialize(), e.info("Click tracking plugin initialized"), Promise.resolve()),
+    /**
+     * Setup cleanup handlers when plugin is loaded
+     * Called after Analytics.js completes plugin loading
+     */
+    loaded: () => (a() && i && s(() => {
+      l && (l.unsubscribe(), l = null), i && (i.cleanup(), i = null, e.info("Click tracking cleaned up on page unload"));
+    }), !0)
+  };
+};
+export {
+  g as dotAnalyticsClickPlugin
+};

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

@@ -0,0 +1,12 @@
+import { DotCMSContentClickPayload } from '../../shared/models';
+import { createPluginLogger } from '../../shared/utils/dot-analytics.utils';
+/**
+ * Handles click events on elements within a contentlet.
+ * The contentlet element is already known since we attach listeners to contentlets.
+ *
+ * @param event - The mouse event
+ * @param contentletElement - The contentlet container element
+ * @param trackCallback - Callback to execute if the click is valid
+ * @param logger - Logger instance for debug messages
+ */
+export declare const handleContentletClick: (event: MouseEvent, contentletElement: HTMLElement, trackCallback: (eventName: string, payload: DotCMSContentClickPayload) => void, logger: ReturnType<typeof createPluginLogger>) => void;

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

@@ -0,0 +1,55 @@
+import { CLICKABLE_ELEMENTS_SELECTOR as l, CLICK_EVENT_TYPE as m } from "../../shared/constants/dot-analytics.constants.js";
+import { extractContentletData as p } from "../../shared/utils/dot-analytics.utils.js";
+import { getViewportMetrics as b } from "../impression/dot-analytics.impression.utils.js";
+const _ = (r, o, c, e) => {
+  const a = r.target;
+  e.debug("Click detected on:", a);
+  const t = a.closest(l);
+  if (!t) {
+    e.debug("No <a> or <button> found in click path");
+    return;
+  }
+  if (!o.contains(t)) {
+    e.debug("Click was outside contentlet boundary");
+    return;
+  }
+  e.debug("Found clickable element:", t);
+  const n = p(o);
+  if (!n.identifier) {
+    e.debug("Contentlet has no identifier");
+    return;
+  }
+  e.debug("Contentlet data:", n);
+  const d = b(o), s = [];
+  for (const i of t.attributes)
+    !i.name.startsWith("data-dot-analytics") && i.name !== "class" && i.name !== "id" && i.name !== "href" && s.push(`${i.name}:${i.value}`);
+  const f = parseInt(o.dataset.dotAnalyticsDomIndex || "-1", 10), u = {
+    content: {
+      identifier: n.identifier,
+      inode: n.inode,
+      title: n.title,
+      content_type: n.contentType
+    },
+    position: {
+      viewport_offset_pct: d.offsetPercentage,
+      dom_index: f
+    },
+    element: {
+      text: (t.innerText || t.textContent || "").trim().substring(0, 100),
+      // Limit length
+      type: t.tagName.toLowerCase(),
+      id: t.id || "",
+      // Required by backend, empty string if not present
+      class: t.className || "",
+      // Required by backend, empty string if not present
+      href: t.getAttribute("href") || "",
+      // Path as written in HTML (relative), empty string for buttons
+      attributes: s
+      // Additional attributes (data-*, aria-*, target, etc.)
+    }
+  };
+  c(m, u);
+};
+export {
+  _ as handleContentletClick
+};

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

@@ -1,44 +1,32 @@
-import { DotCMSAnalyticsPayload } from '../../shared/dot-content-analytics.model';
+import { AnalyticsBasePayloadWithContext, AnalyticsTrackPayloadWithContext, EnrichedAnalyticsPayload, EnrichedTrackPayload } 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_key, user_id }
- * This enricher plugin runs SECOND to add page/device/utm data.
+ * Plugin that enriches the analytics payload data with page, UTM, and custom data.
+ * Uses Analytics.js lifecycle events to inject enriched data before the main plugin processes it.
  *
- * OPTIMIZED: Uses existing payload.properties data to avoid duplication
+ * 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.
+ * The main plugin runs THIRD to structure events and send to server.
+ *
+ * This plugin is ONLY responsible for data enrichment - NOT for event structuring or business logic.
  */
 export declare const dotAnalyticsEnricherPlugin: () => {
     name: string;
     /**
      * PAGE VIEW ENRICHMENT - Runs after identity context injection
-     * Uses optimized enrichment that leverages analytics.js payload data
+     * Returns enriched payload with page, utm, and custom data added
+     * @returns {EnrichedAnalyticsPayload} Enriched payload ready for event creation
      */
     '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;
+    }) => EnrichedAnalyticsPayload;
     /**
      * TRACK EVENT ENRICHMENT - Runs after identity context injection
-     * Creates structured track events with pre-injected context
+     * Adds page data and timestamp for predefined content events.
+     * For custom events, only adds timestamp.
+     *
+     * @returns {EnrichedTrackPayload} Enriched payload ready for event structuring
      */
     'track:dot-analytics': ({ payload }: {
-        payload: DotCMSAnalyticsPayload;
-    }) => {
-        events: {
-            event_type: "track";
-            local_time: string;
-            data: {
-                src: string;
-                event: string;
-            };
-        }[];
-    };
+        payload: AnalyticsTrackPayloadWithContext;
+    }) => EnrichedTrackPayload;
 };

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

@@ -1,31 +1,41 @@
-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";
+import { DotCMSPredefinedEventType as n } 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",
   /**
    * PAGE VIEW ENRICHMENT - Runs after identity context injection
-   * Uses optimized enrichment that leverages analytics.js payload data
+   * Returns enriched payload with page, utm, and custom data added
+   * @returns {EnrichedAnalyticsPayload} Enriched payload ready for event creation
    */
-  "page:dot-analytics": ({ payload: e }) => i(e),
-  // TODO: Fix this when we haver the final design for the track event
+  "page:dot-analytics": ({
+    payload: t
+  }) => {
+    const e = o(t);
+    if (!e.page)
+      throw new Error("DotCMS Analytics: Missing required page data");
+    return e;
+  },
   /**
    * TRACK EVENT ENRICHMENT - Runs after identity context injection
-   * Creates structured track events with pre-injected context
+   * Adds page data and timestamp for predefined content events.
+   * For custom events, only adds timestamp.
+   *
+   * @returns {EnrichedTrackPayload} Enriched payload ready for event structuring
    */
-  "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
-          }
-        }
-      ]
+  "track:dot-analytics": ({
+    payload: t
+  }) => {
+    const { event: e } = t, r = i();
+    return e === n.CONTENT_IMPRESSION || e === n.CONTENT_CLICK ? {
+      ...t,
+      page: {
+        title: document.title,
+        url: window.location.href
+      },
+      local_time: r
+    } : {
+      ...t,
+      local_time: r
     };
   }
 });

package/lib/core/plugin/identity/dot-analytics.identity.activity-tracker.d.ts

@@ -0,0 +1,20 @@
+import { ANALYTICS_WINDOWS_ACTIVE_KEY, ANALYTICS_WINDOWS_CLEANUP_KEY } from '../../../../../../uve/src/internal.ts';
+import { DotCMSAnalyticsConfig } from '../../shared/models';
+declare global {
+    interface Window {
+        [ANALYTICS_WINDOWS_CLEANUP_KEY]?: () => void;
+        [ANALYTICS_WINDOWS_ACTIVE_KEY]?: boolean;
+    }
+}
+/**
+ * Updates session activity with throttling
+ */
+export declare const updateSessionActivity: () => void;
+/**
+ * Initializes activity tracking
+ */
+export declare const initializeActivityTracking: (config: DotCMSAnalyticsConfig) => void;
+/**
+ * Cleans up activity tracking listeners and resets analytics state
+ */
+export declare const cleanupActivityTracking: () => void;