@dotcms/analytics 0.0.1-beta.42 → 0.0.1-beta.43

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,54 @@
-import { sendAnalyticsEventToServer as r } from "../shared/dot-content-analytics.http.js";
-const s = (a) => {
-  let n = !1;
+import { sendAnalyticsEventToServer as c } from "../shared/dot-content-analytics.http.js";
+const f = (l) => {
+  let t = !1;
   return {
     name: "dot-analytics",
-    config: a,
+    config: l,
     /**
      * 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: () => (t = !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: (n) => {
+      const { config: e, payload: o } = n, { context: i, page: s, device: d, utm: r, local_time: g } = o;
+      if (!t)
         throw new Error("DotAnalytics: Plugin not initialized");
-      const e = {
-        ...t.properties,
-        key: i.apiKey
+      const a = {
+        context: i,
+        events: [
+          {
+            event_type: "pageview",
+            local_time: g,
+            page: s,
+            device: d,
+            ...r && { utm: r }
+          }
+        ]
       };
-      return r(e, i);
+      return e.debug && console.warn("Event to send:", a), c(a, e);
     },
     /**
      * 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: (n) => {
+      const { config: e, payload: o } = n;
+      if (!t)
         throw new Error("DotAnalytics: Plugin not initialized");
-      const e = {
-        ...t.properties,
-        key: i.apiKey
+      const i = {
+        context: o.context
       };
-      return r(e, i);
+      return c(i, e);
     },
     /**
      * Check if the plugin is loaded
      */
-    loaded: () => n
+    loaded: () => t
   };
 };
 export {
-  s as dotAnalytics
+  f as dotAnalytics
 };

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

@@ -0,0 +1,46 @@
+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('analytics').PageData;
+        device: import('../../shared/dot-content-analytics.model').DotCMSDeviceData;
+        type: string;
+        properties: Record<string, unknown>;
+        event: string;
+        options: Record<string, unknown>;
+        context: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext;
+    };
+    /**
+     * 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: string;
+            custom_event: string;
+            local_time: string;
+            properties: {
+                src: string;
+            };
+        }[];
+    };
+};

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

@@ -0,0 +1,33 @@
+import { ANALYTICS_SOURCE_TYPE as r } from "../../shared/dot-content-analytics.constants.js";
+import { getLocalTime as n, enrichPagePayloadOptimized as o } from "../../shared/dot-content-analytics.utils.js";
+const s = () => ({
+  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 }) => o(e),
+  /**
+   * TRACK EVENT ENRICHMENT - Runs after identity context injection
+   * Creates structured track events with pre-injected context
+   */
+  "track:dot-analytics": ({ payload: e }) => {
+    const t = n();
+    return {
+      events: [
+        {
+          event_type: "track",
+          custom_event: e.event,
+          local_time: t,
+          properties: {
+            ...e.properties,
+            src: r
+          }
+        }
+      ]
+    };
+  }
+});
+export {
+  s as dotAnalyticsEnricherPlugin
+};

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

@@ -0,0 +1,80 @@
+import { DotCMSAnalyticsConfig, DotCMSAnalyticsHookParams } from '../../shared/dot-content-analytics.model';
+
+/**
+ * Identity Plugin for DotAnalytics
+ * Handles user ID generation, session management, and activity tracking.
+ * This plugin provides consistent identity context across all analytics events.
+ *
+ * Plugin execution order:
+ * 1. Identity Plugin (this) - Injects context
+ * 2. Enricher Plugin - Adds page/device/utm data
+ * 3. Main Plugin - Sends to server
+ *
+ * @param {DotCMSAnalyticsConfig} config - Configuration object containing server URL, site key, and debug settings
+ * @returns {Object} Plugin object with methods for initialization and event processing
+ */
+export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig) => {
+    name: string;
+    /**
+     * Initialize the identity plugin
+     * Sets up activity tracking for session management
+     */
+    initialize: () => Promise<void>;
+    /**
+     * Inject identity context into page events
+     * This runs BEFORE the enricher plugin
+     */
+    pageStart: ({ payload }: DotCMSAnalyticsHookParams) => {
+        context: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext;
+        type: string;
+        properties: {
+            title: string;
+            url: string;
+            path: string;
+            hash: string;
+            search: string;
+            width: number;
+            height: number;
+            referrer?: string | undefined;
+        };
+        options: Record<string, unknown>;
+        userId: string | null;
+        anonymousId: string;
+        meta: {
+            rid: string;
+            ts: number;
+            hasCallback: boolean;
+        };
+    };
+    /**
+     * Inject identity context into track events
+     * This runs BEFORE the enricher plugin
+     */
+    trackStart: ({ payload }: DotCMSAnalyticsHookParams) => {
+        context: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext;
+        type: string;
+        properties: {
+            title: string;
+            url: string;
+            path: string;
+            hash: string;
+            search: string;
+            width: number;
+            height: number;
+            referrer?: string | undefined;
+        };
+        options: Record<string, unknown>;
+        userId: string | null;
+        anonymousId: string;
+        meta: {
+            rid: string;
+            ts: number;
+            hasCallback: boolean;
+        };
+    };
+    /**
+     * Clean up on plugin unload
+     * Sets up cleanup handlers for activity tracking
+     */
+    loaded: () => boolean;
+};

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

@@ -0,0 +1,40 @@
+import { getAnalyticsContext as i } from "../../shared/dot-content-analytics.utils.js";
+import { cleanupActivityTracking as r, initializeActivityTracking as o } from "../../shared/dot-content-analytics.activity-tracker.js";
+const c = (t) => ({
+  name: "dot-analytics-identity",
+  /**
+   * Initialize the identity plugin
+   * Sets up activity tracking for session management
+   */
+  initialize: () => (o(t), Promise.resolve()),
+  /**
+   * Inject identity context into page events
+   * This runs BEFORE the enricher plugin
+   */
+  pageStart: ({ payload: e }) => {
+    const n = i(t);
+    return {
+      ...e,
+      context: n
+    };
+  },
+  /**
+   * Inject identity context into track events
+   * This runs BEFORE the enricher plugin
+   */
+  trackStart: ({ payload: e }) => {
+    const n = i(t);
+    return {
+      ...e,
+      context: n
+    };
+  },
+  /**
+   * Clean up on plugin unload
+   * Sets up cleanup handlers for activity tracking
+   */
+  loaded: () => (typeof window < "u" && (window.addEventListener("beforeunload", r), window.addEventListener("pagehide", r)), !0)
+});
+export {
+  c as dotAnalyticsIdentityPlugin
+};

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

@@ -0,0 +1,24 @@
+/**
+ * Updates activity timestamp
+ */
+export declare const updateActivityTime: () => void;
+/**
+ * Checks if user has been inactive
+ */
+export declare const isUserInactive: () => boolean;
+/**
+ * Checks if a new day has started since session creation
+ */
+export declare const hasPassedMidnight: (sessionStartTime: number) => boolean;
+/**
+ * Gets the last activity time
+ */
+export declare const getLastActivityTime: () => number;
+/**
+ * Extracts UTM parameters from current location
+ */
+export declare const extractUTMParameters: () => Record<string, string>;
+/**
+ * Compares UTM parameters to detect campaign changes
+ */
+export declare const hasUTMChanged: (currentUTM: Record<string, string>) => boolean;

package/lib/dotAnalytics/shared/dot-content-analytics.activity-tracker.d.ts

@@ -0,0 +1,29 @@
+import { DotCMSAnalyticsConfig } from './dot-content-analytics.model';
+
+/**
+ * Updates session activity with throttling
+ */
+export declare const updateSessionActivity: () => void;
+/**
+ * Gets session information for debugging
+ */
+export declare const getSessionInfo: () => {
+    lastActivity: number;
+    isActive: boolean;
+};
+/**
+ * Initializes activity tracking
+ */
+export declare const initializeActivityTracking: (config: DotCMSAnalyticsConfig) => void;
+/**
+ * Cleans up activity tracking listeners
+ */
+export declare const cleanupActivityTracking: () => void;
+/**
+ * Checks if user has been inactive
+ */
+export declare const isUserInactive: () => boolean;
+/**
+ * Gets last activity time
+ */
+export declare const getLastActivity: () => number;

package/lib/dotAnalytics/shared/dot-content-analytics.activity-tracker.js

@@ -0,0 +1,86 @@
+import { DEFAULT_SESSION_TIMEOUT_MINUTES as c, ACTIVITY_EVENTS as r } from "./dot-content-analytics.constants.js";
+class o {
+  constructor() {
+    this.activityListeners = [], this.lastActivityTime = Date.now(), this.inactivityTimer = null, this.isThrottled = !1, this.config = null, this.ACTIVITY_THROTTLE_MS = 1e3;
+  }
+  // Throttle activity events to max 1 per second
+  /**
+   * Updates activity timestamp (throttled for performance)
+   */
+  updateActivityTime() {
+    this.lastActivityTime = Date.now(), this.inactivityTimer && clearTimeout(this.inactivityTimer), this.inactivityTimer = setTimeout(
+      () => {
+        var i;
+        (i = this.config) != null && i.debug && console.warn("DotCMS Analytics: User became inactive after timeout"), this.inactivityTimer = null;
+      },
+      c * 60 * 1e3
+    );
+  }
+  /**
+   * Checks if user has been inactive
+   */
+  isUserInactive() {
+    const i = c * 60 * 1e3;
+    return Date.now() - this.lastActivityTime > i;
+  }
+  /**
+   * Gets last activity time
+   */
+  getLastActivity() {
+    return this.lastActivityTime;
+  }
+  /**
+   * Updates session activity with throttling
+   */
+  updateSessionActivity() {
+    this.isThrottled || (this.isThrottled = !0, this.updateActivityTime(), setTimeout(() => {
+      this.isThrottled = !1;
+    }, this.ACTIVITY_THROTTLE_MS));
+  }
+  /**
+   * Initializes activity tracking with event listeners
+   */
+  initialize(i) {
+    if (this.cleanup(), this.config = i, typeof window > "u")
+      return;
+    const s = () => this.updateSessionActivity();
+    r.forEach((a) => {
+      window.addEventListener(a, s, { passive: !0 }), this.activityListeners.push(
+        () => window.removeEventListener(a, s)
+      );
+    });
+    const n = () => {
+      document.visibilityState === "visible" && (this.updateSessionActivity(), i.debug && console.warn("DotCMS Analytics: User returned to tab, session reactivated"));
+    };
+    document.addEventListener("visibilitychange", n), this.activityListeners.push(
+      () => document.removeEventListener("visibilitychange", n)
+    ), this.updateActivityTime(), i.debug && console.warn("DotCMS Analytics: Activity tracking initialized");
+  }
+  /**
+   * Cleans up all activity tracking listeners
+   */
+  cleanup() {
+    this.activityListeners.forEach((i) => i()), this.activityListeners = [], this.inactivityTimer && (clearTimeout(this.inactivityTimer), this.inactivityTimer = null), this.config = null;
+  }
+  /**
+   * Gets session information for debugging
+   */
+  getSessionInfo() {
+    return {
+      lastActivity: this.getLastActivity(),
+      isActive: !this.isUserInactive()
+    };
+  }
+}
+const t = new o(), h = () => {
+  t.updateSessionActivity();
+}, l = (e) => {
+  t.initialize(e);
+}, T = () => {
+  t.cleanup();
+};
+export {
+  T as cleanupActivityTracking,
+  l as initializeActivityTracking,
+  h as updateSessionActivity
+};

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

@@ -1,13 +1,22 @@
 export declare const ANALYTICS_WINDOWS_KEY = "dotAnalytics";
 export declare const ANALYTICS_SOURCE_TYPE = "dotAnalytics";
 export declare const ANALYTICS_ENDPOINT = "/api/v1/analytics/content/event";
-export declare const ANALYTICS_PAGEVIEW_EVENT = "PAGE_REQUEST";
-export declare const ANALYTICS_TRACK_EVENT = "TRACK_EVENT";
 export declare const EXPECTED_UTM_KEYS: string[];
 /**
- * The type of event.
+ * Session configuration constants
  */
-export declare enum EventType {
-    Track = "track",
-    PageView = "pageview"
-}
+export declare const DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
+export declare const SESSION_STORAGE_KEY = "dot_analytics_session_id";
+export declare const SESSION_START_KEY = "dot_analytics_session_start";
+export declare const SESSION_UTM_KEY = "dot_analytics_session_utm";
+/**
+ * User ID configuration constants
+ */
+export declare const USER_ID_KEY = "dot_analytics_user_id";
+/**
+ * Activity tracking configuration
+ * Events used to detect user activity for session management
+ * - click: Detects real user interaction with minimal performance impact
+ * - visibilitychange: Handled separately to detect tab changes
+ */
+export declare const ACTIVITY_EVENTS: string[];

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

@@ -1,10 +1,10 @@
-const E = "dotAnalytics", c = E, a = "/api/v1/analytics/content/event", n = "PAGE_REQUEST", A = ["utm_source", "utm_medium", "utm_campaign", "utm_id"];
-var _ = /* @__PURE__ */ ((t) => (t.Track = "track", t.PageView = "pageview", t))(_ || {});
+const _ = "dotAnalytics", t = _, n = "/api/v1/analytics/content/event", s = 30, E = "dot_analytics_session_id", S = "dot_analytics_user_id", c = ["click"];
 export {
-  a as ANALYTICS_ENDPOINT,
-  n as ANALYTICS_PAGEVIEW_EVENT,
-  c as ANALYTICS_SOURCE_TYPE,
-  E as ANALYTICS_WINDOWS_KEY,
-  A as EXPECTED_UTM_KEYS,
-  _ as EventType
+  c as ACTIVITY_EVENTS,
+  n as ANALYTICS_ENDPOINT,
+  t as ANALYTICS_SOURCE_TYPE,
+  _ as ANALYTICS_WINDOWS_KEY,
+  s as DEFAULT_SESSION_TIMEOUT_MINUTES,
+  E as SESSION_STORAGE_KEY,
+  S as USER_ID_KEY
 };

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

@@ -1,4 +1,4 @@
-import { DotContentAnalyticsConfig } from './dot-content-analytics.model';
+import { DotCMSAnalyticsConfig, DotCMSPageViewRequestBody, DotCMSTrackRequestBody } from './dot-content-analytics.model';
 
 /**
  * Send an analytics event to the server
@@ -6,4 +6,4 @@ import { DotContentAnalyticsConfig } from './dot-content-analytics.model';
  * @param options - The options for the event
  * @returns A promise that resolves to the response from the server
  */
-export declare const sendAnalyticsEventToServer: (data: Record<string, unknown>, options: DotContentAnalyticsConfig) => Promise<void>;
+export declare const sendAnalyticsEventToServer: (payload: DotCMSPageViewRequestBody | DotCMSTrackRequestBody, options: DotCMSAnalyticsConfig) => Promise<void>;

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

@@ -1,11 +1,5 @@
 import { ANALYTICS_ENDPOINT as o } from "./dot-content-analytics.constants.js";
-const a = async (n, t) => {
-  const r = {
-    ...n,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    key: t.apiKey
-  };
-  t.debug && console.warn("DotAnalytics: Event sent:", r);
+const n = async (r, t) => {
   try {
     const e = await fetch(`${t.server}${o}`, {
       method: "POST",
@@ -18,5 +12,5 @@ const a = async (n, t) => {
   }
 };
 export {
-  a as sendAnalyticsEventToServer
+  n as sendAnalyticsEventToServer
 };