@dotcms/analytics 1.1.1 → 1.2.0

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

@@ -1,79 +1,42 @@
-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 { sendAnalyticsEvent as u } from "../shared/dot-content-analytics.http.js";
+import { createAnalyticsQueue as d } from "../shared/queue/dot-analytics.queue.utils.js";
+const v = (t) => {
+  let n = !1;
+  const i = t.queue !== !1;
+  let e = null;
+  const o = (r) => {
+    const { config: c, payload: l } = r;
+    if (!n)
+      throw new Error("DotCMS Analytics: Plugin not initialized");
+    const a = l.events[0], s = l.context;
+    i && e ? e.enqueue(a, s) : u({
+      context: s,
+      events: [a]
+    }, c);
+  };
   return {
     name: "dot-analytics",
-    config: v,
+    config: t,
     /**
-     * Initialize the plugin
+     * Initialize the plugin with optional queue management
      */
-    initialize: () => (r = !0, Promise.resolve()),
+    initialize: () => (n = !0, i && (e = d(t), e.initialize()), 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 }
-            }
-          }
-        ]
-      };
-      return t.debug && console.warn("DotAnalytics: Pageview event to send:", d), c(d, t);
-    },
-    // TODO: Fix this when we haver the final design for the track event
+    page: o,
     /**
      * 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
-            }
-          }
-        ]
-      };
-      return t.debug && console.warn("DotAnalytics: Track event to send (fallback):", n), c(n, t);
-    },
+    track: o,
     /**
      * Check if the plugin is loaded
      */
-    loaded: () => r
+    loaded: () => n
   };
 };
 export {
-  p as dotAnalytics
+  v 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_key, 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;
 };

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

@@ -1,28 +1,50 @@
-import { ANALYTICS_SOURCE_TYPE as n, EVENT_TYPES as r } from "../../shared/dot-content-analytics.constants.js";
-import { getLocalTime as a, enrichPagePayloadOptimized as i } from "../../shared/dot-content-analytics.utils.js";
-const l = () => ({
+import { DotCMSPredefinedEventType as i } from "../../shared/constants/dot-content-analytics.constants.js";
+import { getLocalTime as c, enrichPagePayloadOptimized as s } from "../../shared/dot-content-analytics.utils.js";
+const m = () => ({
   name: "enrich-dot-analytics",
   /**
    * 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: e }) => i(e),
-  // TODO: Fix this when we haver the final design for the track event
+  "page:dot-analytics": ({
+    payload: o
+  }) => {
+    const { context: a, page: t, utm: e, custom: n, local_time: r } = s(o);
+    if (!t)
+      throw new Error("DotCMS Analytics: Missing required page data");
+    return {
+      context: a,
+      events: [
+        {
+          event_type: i.PAGEVIEW,
+          local_time: r,
+          data: {
+            page: t,
+            ...e && { utm: e },
+            ...n && { custom: n }
+          }
+        }
+      ]
+    };
+  },
   /**
    * 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: e }) => {
-    const t = a();
+  "track:dot-analytics": ({
+    payload: o
+  }) => {
+    const { event: a, properties: t, context: e } = o, n = c();
     return {
+      context: e,
       events: [
         {
-          event_type: r.TRACK,
-          local_time: t,
+          event_type: a,
+          local_time: n,
           data: {
-            event: e.event,
-            ...e.properties,
-            src: n
+            custom: t
           }
         }
       ]
@@ -30,5 +52,5 @@ const l = () => ({
   }
 });
 export {
-  l as dotAnalyticsEnricherPlugin
+  m as dotAnalyticsEnricherPlugin
 };

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

@@ -1,4 +1,4 @@
-import { DotCMSAnalyticsConfig, DotCMSAnalyticsHookParams } from '../../shared/dot-content-analytics.model';
+import { AnalyticsBaseParams, DotCMSAnalyticsConfig } from '../../shared/models';
 /**
  * Identity Plugin for DotAnalytics
  * Handles user ID generation, session management, and activity tracking.
@@ -20,12 +20,12 @@ export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig)
      */
     initialize: () => Promise<void>;
     /**
-     * Inject identity context into page events
+     * Inject identity context into page events and updates session activity for session management
      * This runs BEFORE the enricher plugin
      */
-    pageStart: ({ payload }: DotCMSAnalyticsHookParams) => {
-        context: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext;
-        type: string;
+    pageStart: ({ payload }: AnalyticsBaseParams) => {
+        context: import('../../shared/models').DotCMSAnalyticsEventContext;
+        type: "page" | "track";
         properties: {
             title: string;
             url: string;
@@ -37,7 +37,7 @@ export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig)
             referrer?: string;
         };
         options: Record<string, unknown>;
-        userId: string | null;
+        userId: string;
         anonymousId: string;
         meta: {
             rid: string;
@@ -46,12 +46,12 @@ export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig)
         };
     };
     /**
-     * Inject identity context into track events
+     * Inject identity context into track events and updates session activity for session management
      * This runs BEFORE the enricher plugin
      */
-    trackStart: ({ payload }: DotCMSAnalyticsHookParams) => {
-        context: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext;
-        type: string;
+    trackStart: ({ payload }: AnalyticsBaseParams) => {
+        context: import('../../shared/models').DotCMSAnalyticsEventContext;
+        type: "page" | "track";
         properties: {
             title: string;
             url: string;
@@ -63,7 +63,7 @@ export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig)
             referrer?: string;
         };
         options: Record<string, unknown>;
-        userId: string | null;
+        userId: string;
         anonymousId: string;
         meta: {
             rid: string;

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

@@ -1,32 +1,34 @@
-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) => ({
+import { getAnalyticsContext as n } from "../../shared/dot-content-analytics.utils.js";
+import { cleanupActivityTracking as r, updateSessionActivity as o, initializeActivityTracking as a } from "../../shared/dot-content-analytics.activity-tracker.js";
+const s = (t) => ({
   name: "dot-analytics-identity",
   /**
    * Initialize the identity plugin
    * Sets up activity tracking for session management
    */
-  initialize: () => (o(t), Promise.resolve()),
+  initialize: () => (a(t), Promise.resolve()),
   /**
-   * Inject identity context into page events
+   * Inject identity context into page events and updates session activity for session management
    * This runs BEFORE the enricher plugin
    */
   pageStart: ({ payload: e }) => {
-    const n = i(t);
+    o();
+    const i = n(t);
     return {
       ...e,
-      context: n
+      context: i
     };
   },
   /**
-   * Inject identity context into track events
+   * Inject identity context into track events and updates session activity for session management
    * This runs BEFORE the enricher plugin
    */
   trackStart: ({ payload: e }) => {
-    const n = i(t);
+    o();
+    const i = n(t);
     return {
       ...e,
-      context: n
+      context: i
     };
   },
   /**
@@ -36,5 +38,5 @@ const c = (t) => ({
   loaded: () => (typeof window < "u" && (window.addEventListener("beforeunload", r), window.addEventListener("pagehide", r)), !0)
 });
 export {
-  c as dotAnalyticsIdentityPlugin
+  s as dotAnalyticsIdentityPlugin
 };

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

@@ -1,3 +1,4 @@
+import { DotCMSEventUtmData } from '../../shared/models';
 /**
  * Updates activity timestamp
  */
@@ -15,10 +16,10 @@ export declare const hasPassedMidnight: (sessionStartTime: number) => boolean;
  */
 export declare const getLastActivityTime: () => number;
 /**
- * Extracts UTM parameters from current location
+ * Compares UTM parameters to detect campaign changes.
+ * Only checks significant parameters: source, medium, and campaign.
+ * @internal This function is for internal use only.
+ * @param currentUTM - Current UTM parameters in DotCMS format
+ * @returns True if UTM parameters have changed, false otherwise
  */
-export declare const extractUTMParameters: () => Record<string, string>;
-/**
- * Compares UTM parameters to detect campaign changes
- */
-export declare const hasUTMChanged: (currentUTM: Record<string, string>) => boolean;
+export declare const hasUTMChanged: (currentUTM: DotCMSEventUtmData) => boolean;

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

@@ -0,0 +1,70 @@
+export declare const ANALYTICS_WINDOWS_KEY = "dotAnalytics";
+export declare const ANALYTICS_SOURCE_TYPE = "dotAnalytics";
+export declare const ANALYTICS_ENDPOINT = "/api/v1/analytics/content/event";
+/**
+ * Structured event types - events with predefined data shapes
+ * These events have specific data structures and validation
+ */
+export declare const DotCMSPredefinedEventType: {
+    readonly PAGEVIEW: "pageview";
+};
+/**
+ * Type for structured events
+ */
+export type DotCMSPredefinedEventType = (typeof DotCMSPredefinedEventType)[keyof typeof DotCMSPredefinedEventType];
+/**
+ * Custom event type - any string except predefined event types
+ * These events have flexible data structures defined by the user
+ */
+export type DotCMSCustomEventType = Exclude<string, DotCMSPredefinedEventType>;
+/**
+ * Union type for all possible event types
+ */
+export type DotCMSEventType = DotCMSPredefinedEventType | DotCMSCustomEventType;
+/**
+ * Expected UTM parameter keys for campaign tracking
+ */
+export declare const EXPECTED_UTM_KEYS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
+/**
+ * Session configuration constants
+ */
+export declare const DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
+/**
+ * Session storage key for session ID
+ */
+export declare const SESSION_STORAGE_KEY = "dot_analytics_session_id";
+/**
+ * Session storage key for session start time
+ */
+export declare const SESSION_START_KEY = "dot_analytics_session_start";
+/**
+ * Session storage key for session UTM data
+ */
+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: readonly ["click"];
+/**
+ * Default queue configuration for event batching
+ */
+export declare const DEFAULT_QUEUE_CONFIG: {
+    readonly eventBatchSize: 15;
+    readonly flushInterval: 5000;
+};
+/**
+ * The name of the analytics minified script.
+ */
+export declare const ANALYTICS_MINIFIED_SCRIPT_NAME = "ca.min.js";
+/**
+ * Default properties that Analytics.js adds automatically
+ * These should be filtered out to only keep user-provided properties
+ */
+export declare const ANALYTICS_JS_DEFAULT_PROPERTIES: readonly ["title", "url", "path", "hash", "search", "width", "height", "referrer"];

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

@@ -0,0 +1,34 @@
+const E = "/api/v1/analytics/content/event", e = {
+  PAGEVIEW: "pageview"
+}, n = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_term",
+  "utm_content"
+], c = 30, s = "dot_analytics_session_id", T = "dot_analytics_user_id", t = 15, _ = 5e3, o = ["click"], S = {
+  eventBatchSize: t,
+  // Max events per batch - auto-sends when reached
+  flushInterval: _
+  // Time between flushes - sends whatever is queued
+}, I = [
+  "title",
+  "url",
+  "path",
+  "hash",
+  "search",
+  "width",
+  "height",
+  "referrer"
+];
+export {
+  o as ACTIVITY_EVENTS,
+  E as ANALYTICS_ENDPOINT,
+  I as ANALYTICS_JS_DEFAULT_PROPERTIES,
+  S as DEFAULT_QUEUE_CONFIG,
+  c as DEFAULT_SESSION_TIMEOUT_MINUTES,
+  e as DotCMSPredefinedEventType,
+  n as EXPECTED_UTM_KEYS,
+  s as SESSION_STORAGE_KEY,
+  T as USER_ID_KEY
+};

package/lib/core/shared/constants/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Central export point for all DotCMS Analytics constants
+ */
+export * from './dot-content-analytics.constants';

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

@@ -1,4 +1,11 @@
-import { DotCMSAnalyticsConfig } from './dot-content-analytics.model';
+import { ANALYTICS_WINDOWS_ACTIVE_KEY, ANALYTICS_WINDOWS_CLEANUP_KEY } from '../../../../../uve/src/internal.ts';
+import { DotCMSAnalyticsConfig } from './models';
+declare global {
+    interface Window {
+        [ANALYTICS_WINDOWS_CLEANUP_KEY]?: () => void;
+        [ANALYTICS_WINDOWS_ACTIVE_KEY]?: boolean;
+    }
+}
 /**
  * Updates session activity with throttling
  */
@@ -15,7 +22,7 @@ export declare const getSessionInfo: () => {
  */
 export declare const initializeActivityTracking: (config: DotCMSAnalyticsConfig) => void;
 /**
- * Cleans up activity tracking listeners
+ * Cleans up activity tracking listeners and resets analytics state
  */
 export declare const cleanupActivityTracking: () => void;
 /**

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

@@ -1,5 +1,6 @@
-import { DEFAULT_SESSION_TIMEOUT_MINUTES as c, ACTIVITY_EVENTS as r } from "./dot-content-analytics.constants.js";
-class o {
+import { ANALYTICS_WINDOWS_ACTIVE_KEY as o, ANALYTICS_WINDOWS_CLEANUP_KEY as r } from "../../../uve/src/internal/constants.js";
+import { DEFAULT_SESSION_TIMEOUT_MINUTES as c, ACTIVITY_EVENTS as v } from "./constants/dot-content-analytics.constants.js";
+class l {
   constructor() {
     this.activityListeners = [], this.lastActivityTime = Date.now(), this.inactivityTimer = null, this.isThrottled = !1, this.config = null, this.ACTIVITY_THROTTLE_MS = 1e3;
   }
@@ -44,7 +45,7 @@ class o {
     if (this.cleanup(), this.config = i, typeof window > "u")
       return;
     const s = () => this.updateSessionActivity();
-    r.forEach((a) => {
+    v.forEach((a) => {
       window.addEventListener(a, s, { passive: !0 }), this.activityListeners.push(
         () => window.removeEventListener(a, s)
       );
@@ -72,15 +73,15 @@ class o {
     };
   }
 }
-const t = new o(), h = () => {
+const t = new l(), u = () => {
   t.updateSessionActivity();
-}, l = (e) => {
+}, d = (e) => {
   t.initialize(e);
-}, T = () => {
-  t.cleanup();
+}, y = () => {
+  t.cleanup(), typeof window < "u" && (window[o] = !1, window[r] = void 0, window.dispatchEvent(new CustomEvent("dotcms:analytics:cleanup")));
 };
 export {
-  T as cleanupActivityTracking,
-  l as initializeActivityTracking,
-  h as updateSessionActivity
+  y as cleanupActivityTracking,
+  d as initializeActivityTracking,
+  u as updateSessionActivity
 };

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

@@ -1,8 +1,17 @@
-import { DotCMSAnalyticsConfig, DotCMSAnalyticsRequestBody } from './dot-content-analytics.model';
+import { DotCMSAnalyticsConfig, DotCMSEvent, DotCMSRequestBody } from './models';
 /**
- * Send an analytics event to the server
+ * Available transport methods for sending analytics events
+ */
+export declare const TRANSPORT_TYPES: {
+    readonly FETCH: "fetch";
+    readonly BEACON: "beacon";
+};
+export type TransportType = (typeof TRANSPORT_TYPES)[keyof typeof TRANSPORT_TYPES];
+/**
+ * Send analytics events to the server
  * @param payload - The event payload data
  * @param config - The analytics configuration
- * @returns A promise that resolves when the request is complete
+ * @param transportType - Transport method: 'fetch' (default) or 'beacon' (for page unload)
+ * @returns A promise that resolves when the request is complete (fetch only)
  */
-export declare const sendAnalyticsEventToServer: (payload: DotCMSAnalyticsRequestBody, config: DotCMSAnalyticsConfig) => Promise<void>;
+export declare const sendAnalyticsEvent: (payload: DotCMSRequestBody<DotCMSEvent>, config: DotCMSAnalyticsConfig, transportType?: TransportType) => Promise<void>;

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

@@ -1,29 +1,41 @@
-import { ANALYTICS_ENDPOINT as a } from "./dot-content-analytics.constants.js";
-const i = async (o, t) => {
+import { ANALYTICS_ENDPOINT as l } from "./constants/dot-content-analytics.constants.js";
+const d = async (s, n, o = "fetch") => {
+  const a = `${n.server}${l}`, c = JSON.stringify(s);
+  if (n.debug && console.warn(
+    `DotCMS Analytics: Sending ${s.events.length} event(s) via ${o}`,
+    o === "fetch" ? { payload: s } : void 0
+  ), o === "beacon") {
+    if (navigator.sendBeacon) {
+      const e = new Blob([c], { type: "application/json" });
+      !navigator.sendBeacon(a, e) && n.debug && console.warn("DotCMS Analytics: sendBeacon failed (queue might be full)");
+    } else
+      return n.debug && console.warn("DotCMS Analytics: sendBeacon not available, using fetch fallback"), d(s, n, "fetch");
+    return;
+  }
   try {
-    const e = await fetch(`${t.server}${a}`, {
+    const e = await fetch(a, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(o)
+      body: c
     });
     if (!e.ok) {
-      const n = e.statusText || "Unknown Error", s = `HTTP ${e.status}: ${n}`;
+      const i = e.statusText || "Unknown Error", r = `HTTP ${e.status}: ${i}`;
       try {
-        const r = await e.json();
-        r.message ? console.warn(`DotAnalytics: ${r.message} (${s})`) : console.warn(
-          `DotAnalytics: ${s} - No error message in response`
+        const t = await e.json();
+        t.message ? console.warn(`DotCMS Analytics: ${t.message} (${r})`) : console.warn(
+          `DotCMS Analytics: ${r} - No error message in response`
         );
-      } catch (r) {
+      } catch (t) {
         console.warn(
-          `DotAnalytics: ${s} - Failed to parse error response:`,
-          r
+          `DotCMS Analytics: ${r} - Failed to parse error response:`,
+          t
         );
       }
     }
   } catch (e) {
-    console.error("DotAnalytics: Error sending event:", e);
+    console.error("DotCMS Analytics: Error sending event:", e);
   }
 };
 export {
-  i as sendAnalyticsEventToServer
+  d as sendAnalyticsEvent
 };