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

package/README.md

@@ -115,6 +115,59 @@ track(eventName: string, properties?: Record<string, unknown>): void
 | `server` | `string` | ✅ | - | Your dotCMS server URL |
 | `debug` | `boolean` | ❌ | `false` | Enable verbose logging |
 | `autoPageView` | `boolean` | ❌ | React: `true` / Standalone: `false` | Auto track page views on route changes |
+| `queueConfig` | `QueueConfig` | ❌ | See below | Event batching configuration |
+
+### Queue Configuration
+
+The `queueConfig` option controls event batching:
+
+-   **`false`**: Disable queuing, send events immediately
+-   **`undefined` (default)**: Enable queuing with default settings
+-   **`QueueConfig` object**: Enable queuing with custom settings
+
+| Option           | Type     | Default | Description                                      |
+| ---------------- | -------- | ------- | ------------------------------------------------ |
+| `eventBatchSize` | `number` | `15`    | Max events per batch - auto-sends when reached   |
+| `flushInterval`  | `number` | `5000`  | Time between flushes - sends pending events (ms) |
+
+**How it works:**
+
+-   ✅ Send immediately when `eventBatchSize` reached (e.g., 15 events)
+-   ✅ Send pending events every `flushInterval` (e.g., 5 seconds)
+-   ✅ Auto-flush on page navigation/close using `visibilitychange` + `pagehide` events
+-   Example: If you have 10 events and 5 seconds pass → sends those 10
+
+**About page unload handling:**
+
+The SDK uses modern APIs (`visibilitychange` + `pagehide`) instead of `beforeunload`/`unload` to ensure:
+
+-   ✅ Better reliability on mobile devices
+-   ✅ Compatible with browser back/forward cache (bfcache)
+-   ✅ Events are sent via `navigator.sendBeacon()` for guaranteed delivery
+-   ✅ No negative impact on page performance
+
+**Example: Disable queuing for immediate sends**
+
+```javascript
+const analytics = initializeContentAnalytics({
+    siteAuth: 'abc123',
+    server: 'https://your-dotcms.com',
+    queue: false // Send events immediately without batching
+});
+```
+
+**Example: Custom queue config**
+
+```javascript
+const analytics = initializeContentAnalytics({
+    siteAuth: 'abc123',
+    server: 'https://your-dotcms.com',
+    queue: {
+        eventBatchSize: 10, // Auto-send when 10 events queued
+        flushInterval: 3000 // Or send every 3 seconds
+    }
+});
+```
 
 ## 🛠️ Usage Examples
 

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

@@ -3,28 +3,29 @@ import { DotCMSAnalyticsConfig, DotCMSAnalyticsParams } from '../shared/models';
  * Analytics plugin for tracking page views and custom events in DotCMS applications.
  * This plugin handles sending analytics data to the DotCMS server, managing initialization,
  * and processing both automatic and manual tracking events.
+ * Supports optional queue management for batching events before sending.
  *
  * @param {DotCMSAnalyticsConfig} config - Configuration object containing API key, server URL,
- *                                     debug mode and auto page view settings
+ *                                     debug mode, auto page view settings, and queue config
  * @returns {Object} Plugin object with methods for initialization and event tracking
  */
 export declare const dotAnalytics: (config: DotCMSAnalyticsConfig) => {
     name: string;
     config: DotCMSAnalyticsConfig;
     /**
-     * Initialize the plugin
+     * Initialize the plugin with optional queue management
      */
     initialize: () => Promise<void>;
     /**
      * Track a page view event
      * The enricher plugin has already built the complete request body
      */
-    page: (params: DotCMSAnalyticsParams) => Promise<void>;
+    page: (params: DotCMSAnalyticsParams) => void;
     /**
      * Track a custom event
      * The enricher plugin has already built the complete request body
      */
-    track: (params: DotCMSAnalyticsParams) => Promise<void>;
+    track: (params: DotCMSAnalyticsParams) => void;
     /**
      * Check if the plugin is loaded
      */

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

@@ -1,41 +1,36 @@
-import { sendAnalyticsEventToServer as r } from "../shared/dot-content-analytics.http.js";
-const s = (a) => {
+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: a,
+    config: t,
     /**
-     * Initialize the plugin
+     * Initialize the plugin with optional queue management
      */
-    initialize: () => (n = !0, Promise.resolve()),
+    initialize: () => (n = !0, i && (e = d(t), e.initialize()), Promise.resolve()),
     /**
      * Track a page view event
      * The enricher plugin has already built the complete request body
      */
-    page: (e) => {
-      const { config: o, payload: t } = e;
-      if (!n)
-        throw new Error("DotCMS Analytics: Plugin not initialized");
-      const i = {
-        context: t.context,
-        events: t.events
-      };
-      return r(i, o);
-    },
+    page: o,
     /**
      * Track a custom event
      * The enricher plugin has already built the complete request body
      */
-    track: (e) => {
-      const { config: o, payload: t } = e;
-      if (!n)
-        throw new Error("DotCMS Analytics: Plugin not initialized");
-      const i = {
-        context: t.context,
-        events: t.events
-      };
-      return r(i, o);
-    },
+    track: o,
     /**
      * Check if the plugin is loaded
      */
@@ -43,5 +38,5 @@ const s = (a) => {
   };
 };
 export {
-  s as dotAnalytics
+  v as dotAnalytics
 };

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

@@ -29,8 +29,17 @@ export declare const EXPECTED_UTM_KEYS: readonly ["utm_source", "utm_medium", "u
  * 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
@@ -43,6 +52,13 @@ export declare const USER_ID_KEY = "dot_analytics_user_id";
  * - 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.
  */

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

@@ -1,12 +1,17 @@
-const t = "/api/v1/analytics/content/event", _ = {
+const E = "/api/v1/analytics/content/event", e = {
   PAGEVIEW: "pageview"
-}, e = [
+}, n = [
   "utm_source",
   "utm_medium",
   "utm_campaign",
   "utm_term",
   "utm_content"
-], E = 30, n = "dot_analytics_session_id", c = "dot_analytics_user_id", s = ["click"], o = [
+], 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",
@@ -17,12 +22,13 @@ const t = "/api/v1/analytics/content/event", _ = {
   "referrer"
 ];
 export {
-  s as ACTIVITY_EVENTS,
-  t as ANALYTICS_ENDPOINT,
-  o as ANALYTICS_JS_DEFAULT_PROPERTIES,
-  E as DEFAULT_SESSION_TIMEOUT_MINUTES,
-  _ as DotCMSPredefinedEventType,
-  e as EXPECTED_UTM_KEYS,
-  n as SESSION_STORAGE_KEY,
-  c as USER_ID_KEY
+  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/dot-content-analytics.http.d.ts

@@ -1,8 +1,17 @@
 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: DotCMSRequestBody<DotCMSEvent>, 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,23 +1,34 @@
-import { ANALYTICS_ENDPOINT as a } from "./constants/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 {
-    t.debug && console.warn("DotCMS Analytics: HTTP Body to send:", JSON.stringify(o, null, 2));
-    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", r = `HTTP ${e.status}: ${n}`;
+      const i = e.statusText || "Unknown Error", r = `HTTP ${e.status}: ${i}`;
       try {
-        const s = await e.json();
-        s.message ? console.warn(`DotCMS Analytics: ${s.message} (${r})`) : console.warn(
+        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 (s) {
+      } catch (t) {
         console.warn(
           `DotCMS Analytics: ${r} - Failed to parse error response:`,
-          s
+          t
         );
       }
     }
@@ -26,5 +37,5 @@ const i = async (o, t) => {
   }
 };
 export {
-  i as sendAnalyticsEventToServer
+  d as sendAnalyticsEvent
 };

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

@@ -2,6 +2,16 @@ import { DotCMSAnalyticsEventContext, DotCMSEventPageData, DotCMSEventUtmData }
 import { JsonObject } from './event.model';
 import { DotCMSAnalyticsRequestBody } from './request.model';
 import { DotCMSCustomEventType } from '../constants';
+/**
+ * Configuration for event queue management.
+ * Controls how events are batched before sending to the server.
+ */
+export interface QueueConfig {
+    /** Maximum events per batch - auto-sends when reached (default: 15) */
+    eventBatchSize?: number;
+    /** Time in milliseconds between flushes - sends pending events (default: 5000) */
+    flushInterval?: number;
+}
 /**
  * Main interface for the DotCMS Analytics SDK.
  * Provides the core methods for tracking page views and custom events.
@@ -40,6 +50,13 @@ export interface DotCMSAnalyticsConfig {
      * The site auth for authenticating with the Analytics service.
      */
     siteAuth: string;
+    /**
+     * Queue configuration for event batching:
+     * - `false`: Disable queuing, send events immediately
+     * - `true` or `undefined` (default): Enable queuing with default settings
+     * - `QueueConfig`: Enable queuing with custom settings
+     */
+    queue?: QueueConfig | boolean;
 }
 /**
  * Track event payload with context.

package/lib/core/shared/queue/dot-analytics.queue.utils.d.ts

@@ -0,0 +1,28 @@
+import { DotCMSAnalyticsConfig, DotCMSAnalyticsEventContext, DotCMSEvent } from '../models';
+/**
+ * Creates a queue manager for batching analytics events.
+ * Uses factory function pattern consistent with the plugin architecture.
+ */
+export declare const createAnalyticsQueue: (config: DotCMSAnalyticsConfig) => {
+    /**
+     * Initialize the queue with smart batching
+     */
+    initialize: () => void;
+    /**
+     * Add event to queue
+     * smartQueue handles all batching logic automatically:
+     * - Sends immediately when eventBatchSize reached (with throttle: false)
+     * - Sends pending events every flushInterval
+     */
+    enqueue: (event: DotCMSEvent, context: DotCMSAnalyticsEventContext) => void;
+    /**
+     * Get queue size for debugging
+     * Returns the number of events in smartQueue
+     */
+    size: () => number;
+    /**
+     * Clean up queue resources
+     * Flushes remaining events and cleans up listeners
+     */
+    cleanup: () => void;
+};

package/lib/core/shared/queue/dot-analytics.queue.utils.js

@@ -0,0 +1,73 @@
+import p from "@analytics/queue-utils";
+import { DEFAULT_QUEUE_CONFIG as c } from "../constants/dot-content-analytics.constants.js";
+import { sendAnalyticsEvent as y } from "../dot-content-analytics.http.js";
+const z = (n) => {
+  let e = null, i = null, o = "fetch";
+  const l = {
+    ...c,
+    ...typeof n.queue == "object" ? n.queue : {}
+  }, f = (t) => {
+    if (!i) return;
+    n.debug && console.log(`DotCMS Analytics Queue: Sending batch of ${t.length} event(s)`, {
+      events: t,
+      transport: o
+    }), y({ context: i, events: t }, n, o);
+  }, u = () => {
+    !e || e.size() === 0 || !i || (n.debug && console.warn(
+      `DotCMS Analytics: Flushing ${e.size()} events (page hidden/unload)`
+    ), o = "beacon", e.flush(!0));
+  }, d = () => {
+    document.visibilityState === "hidden" && u();
+  };
+  return {
+    /**
+     * Initialize the queue with smart batching
+     */
+    initialize: () => {
+      e = p(
+        (t) => {
+          f(t);
+        },
+        {
+          max: l.eventBatchSize,
+          interval: l.flushInterval,
+          throttle: !1
+          // Always false - enables both batch size and interval triggers
+        }
+      ), typeof window < "u" && typeof document < "u" && (document.addEventListener("visibilitychange", d), window.addEventListener("pagehide", u));
+    },
+    /**
+     * Add event to queue
+     * smartQueue handles all batching logic automatically:
+     * - Sends immediately when eventBatchSize reached (with throttle: false)
+     * - Sends pending events every flushInterval
+     */
+    enqueue: (t, s) => {
+      if (i = s, !!e) {
+        if (n.debug) {
+          const a = e.size() + 1, r = l.eventBatchSize ?? c.eventBatchSize, h = a >= r;
+          console.log(
+            `DotCMS Analytics Queue: Event added. Queue size: ${a}/${r}${h ? " (full, sending...)" : ""}`,
+            { eventType: t.event_type, event: t }
+          );
+        }
+        e.push(t);
+      }
+    },
+    /**
+     * Get queue size for debugging
+     * Returns the number of events in smartQueue
+     */
+    size: () => (e == null ? void 0 : e.size()) ?? 0,
+    /**
+     * Clean up queue resources
+     * Flushes remaining events and cleans up listeners
+     */
+    cleanup: () => {
+      u(), typeof window < "u" && typeof document < "u" && (document.removeEventListener("visibilitychange", d), window.removeEventListener("pagehide", u)), e = null, i = null, o = "fetch";
+    }
+  };
+};
+export {
+  z as createAnalyticsQueue
+};

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

@@ -0,0 +1 @@
+export { createAnalyticsQueue } from './dot-analytics.queue.utils';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/analytics",
-  "version": "1.1.1-next.4",
+  "version": "1.1.1-next.5",
   "description": "Official JavaScript library for Content Analytics with DotCMS.",
   "repository": {
     "type": "git",
@@ -23,6 +23,7 @@
     "analytics": "^0.8.0",
     "@analytics/core": "^0.13.0",
     "@analytics/storage-utils": "^0.4.0",
+    "@analytics/queue-utils": "^0.1.3",
     "@dotcms/uve": "latest"
   },
   "peerDependencies": {