@dotcms/analytics 1.1.1 → 1.2.0

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

@@ -0,0 +1,191 @@
+import { DotCMSAnalyticsEventContext, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
+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.
+ */
+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;
+    /**
+     * 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;
+}
+/**
+ * Configuration interface for DotCMS Analytics SDK.
+ * Contains all necessary settings for initializing and configuring the analytics client.
+ */
+export interface DotCMSAnalyticsConfig {
+    /**
+     * The URL of the Analytics server endpoint.
+     */
+    server: string;
+    /**
+     * Enable debug mode to get additional logging information.
+     */
+    debug: boolean;
+    /**
+     * Automatically track page views when set to true.
+     */
+    autoPageView?: boolean;
+    /**
+     * 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.
+ * This is the payload for custom track events after the identity plugin adds context.
+ * Used in the track:dot-analytics enricher plugin.
+ */
+export interface AnalyticsTrackPayloadWithContext extends AnalyticsBasePayload {
+    /** The custom event name (any string except 'pageview') */
+    event: DotCMSCustomEventType;
+    /** Analytics context added by identity plugin */
+    context: DotCMSAnalyticsEventContext;
+}
+/**
+ * Parameters passed to DotCMS Analytics plugin methods (after enrichment).
+ * The payload is the complete request body ready to send to the server.
+ */
+export interface DotCMSAnalyticsParams {
+    /** Configuration for the analytics client */
+    config: DotCMSAnalyticsConfig;
+    /** The complete request body */
+    payload: DotCMSAnalyticsRequestBody;
+}
+type AnalyticsBasePayloadType = 'page' | 'track';
+/**
+ * Analytics.js hook parameter types for DotCMS.
+ * Represents the payload structure used by Analytics.js lifecycle hooks
+ * for intercepting and modifying analytics events.
+ */
+export interface AnalyticsBasePayload {
+    /** The type of analytics event */
+    type: AnalyticsBasePayloadType;
+    /** Properties associated with the event */
+    properties: {
+        /** Page title */
+        title: string;
+        /** Page URL */
+        url: string;
+        /** Page path */
+        path: string;
+        /** URL hash fragment */
+        hash: string;
+        /** URL search parameters */
+        search: string;
+        /** Viewport width */
+        width: number;
+        /** Viewport height */
+        height: number;
+        /** Referrer URL */
+        referrer?: string;
+    };
+    /** Configuration options for the event */
+    options: Record<string, unknown>;
+    /** User identifier */
+    userId: string;
+    /** Anonymous user identifier */
+    anonymousId: string;
+    /** Metadata about the event */
+    meta: {
+        /** Request identifier */
+        rid: string;
+        /** Timestamp */
+        ts: number;
+        /** Whether the event has a callback function */
+        hasCallback: boolean;
+    };
+}
+/**
+ * Analytics.js payload with context.
+ * This is the result of enriching the base Analytics.js payload
+ * with context data added by the identity plugin.
+ */
+export interface AnalyticsBasePayloadWithContext extends AnalyticsBasePayload {
+    context: DotCMSAnalyticsEventContext;
+}
+/**
+ * Enriched analytics payload with DotCMS-specific data.
+ * This is the result of enriching the base Analytics.js payload with context (from identity plugin)
+ * and then adding page, UTM, and custom data (from enricher plugin).
+ */
+export type EnrichedAnalyticsPayload = AnalyticsBasePayloadWithContext & {
+    /** Page data for the current page */
+    page: DotCMSEventPageData;
+    /** UTM parameters for campaign tracking */
+    utm?: DotCMSEventUtmData;
+    /** Custom data associated with the event (any valid JSON) */
+    custom?: JsonObject;
+    /** Local timestamp when the event occurred */
+    local_time: string;
+};
+/**
+ * Analytics.js instance structure for DotCMS.
+ * Represents the internal structure of an Analytics.js instance,
+ * providing access to plugins, storage, and event configuration.
+ */
+export interface DotCMSAnalyticsInstance {
+    /** Available plugins and their configurations */
+    plugins: Record<string, unknown>;
+    /** Storage mechanisms for analytics data */
+    storage: Record<string, unknown>;
+    /** Event configuration */
+    events: {
+        /** Core event types */
+        core: string[];
+        /** Plugin-specific event types */
+        plugins: string[];
+    };
+}
+/**
+ * Base parameters structure passed by Analytics.js to plugin hooks.
+ * Contains all the context and data needed for Analytics.js lifecycle hooks
+ * to process and modify analytics events.
+ */
+export interface AnalyticsBaseParams {
+    /** The event payload data */
+    payload: AnalyticsBasePayload;
+    /** The analytics instance */
+    instance: DotCMSAnalyticsInstance;
+    /** Global configuration settings */
+    config: Record<string, unknown>;
+    /** Available plugins and their status */
+    plugins: Record<string, {
+        /** Whether the plugin is enabled */
+        enabled: boolean;
+        /** Whether the plugin is initialized */
+        initialized: boolean;
+        /** Whether the plugin is loaded */
+        loaded: boolean;
+        /** Plugin-specific configuration */
+        config: Record<string, unknown>;
+    }>;
+}
+export {};

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

@@ -0,0 +1,24 @@
+import { DotCMSAnalyticsEventContext } from './data.model';
+import { DotCMSCustomEvent, DotCMSEvent, DotCMSPageViewEvent } from './event.model';
+/**
+ * Analytics request body for DotCMS Analytics.
+ * Generic structure sent to the DotCMS analytics server.
+ */
+export interface DotCMSRequestBody<T extends DotCMSEvent> {
+    /** Context information shared across all events */
+    context: DotCMSAnalyticsEventContext;
+    /** Array of analytics events to be tracked */
+    events: T[];
+}
+/**
+ * Specific request body type for PageView events
+ */
+export type DotCMSPageViewRequestBody = DotCMSRequestBody<DotCMSPageViewEvent>;
+/**
+ * Specific request body type for Custom events
+ */
+export type DotCMSCustomEventRequestBody = DotCMSRequestBody<DotCMSCustomEvent>;
+/**
+ * Union type for all possible request bodies
+ */
+export type DotCMSAnalyticsRequestBody = DotCMSPageViewRequestBody | DotCMSCustomEventRequestBody;

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/lib/react/components/DotContentAnalytics.d.ts

@@ -1,5 +1,5 @@
 import { ReactElement } from 'react';
-import { DotCMSAnalyticsConfig } from '../../core/shared/dot-content-analytics.model';
+import { DotCMSAnalyticsConfig } from '../../core/shared/models';
 /**
  * Client bootstrapper for dotCMS Analytics in React/Next.
  * - No UI: initializes the analytics singleton from props or env config.

package/lib/react/hook/useContentAnalytics.d.ts

@@ -1,29 +1,57 @@
-import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../core/shared/dot-content-analytics.model';
+import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../core/shared/models';
 /**
- * Custom hook that handles analytics tracking for anonymous users.
- * Provides methods to track events and page views with automatic timestamp injection.
- * Automatically disables tracking when inside the UVE editor.
+ * React hook for tracking user interactions and page views in your DotCMS application.
+ *
+ * Use this hook to add analytics tracking to your React components. It automatically
+ * handles user sessions, device information, and UTM campaign parameters.
+ *
+ * **Important:** Tracking is automatically disabled when editing content in DotCMS to avoid
+ * polluting your analytics data with editor activity.
  *
  * @example
+ * Basic usage - Track custom events
  * ```tsx
- * function Button({ title, urlTitle }) {
+ * function ProductCard({ title, price }) {
  *   const { track } = useContentAnalytics({
  *     server: 'https://demo.dotcms.com',
- *     siteKey: 'my-site-key',
+ *     siteAuth: 'my-site-auth',
  *     debug: false
  *   });
  *
- *   // Track button click with custom properties
- *   return (
- *     <button onClick={() => track('btn-click', { title, urlTitle })}>
- *       See Details →
- *     </button>
- *   );
+ *   const handleAddToCart = () => {
+ *     track('add-to-cart', {
+ *       product: title,
+ *       price: price
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleAddToCart}>Add to Cart</button>;
+ * }
+ * ```
+ *
+ * @example
+ * Track page views manually
+ * ```tsx
+ * function ArticlePage({ article }) {
+ *   const { pageView } = useContentAnalytics({
+ *     server: 'https://demo.dotcms.com',
+ *     siteKey: 'your-site-key'
+ *   });
+ *
+ *   useEffect(() => {
+ *     pageView({
+ *       category: article.category,
+ *       author: article.author
+ *     });
+ *   }, [article.id]);
  * }
  * ```
  *
- * @param {DotCMSAnalyticsConfig} config - Required configuration object for analytics initialization
- * @returns {DotCMSAnalytics} The analytics instance with tracking capabilities
- * @throws {Error} When analytics initialization fails due to invalid configuration
+ * @param config - Configuration object with server URL and site key
+ * @param config.server - The URL of your DotCMS Analytics server
+ * @param config.siteKey - Your unique site key for authentication
+ * @param config.debug - Optional. Set to true to see analytics events in the console
+ * @returns Object with `track()` and `pageView()` methods for analytics tracking
+ * @throws {Error} If the configuration is invalid (missing server or siteKey)
  */
 export declare const useContentAnalytics: (config: DotCMSAnalyticsConfig) => DotCMSAnalytics;

package/lib/react/hook/useContentAnalytics.js

@@ -1,32 +1,29 @@
-import { useRef as l, useCallback as n } from "react";
-import { getUVEState as r } from "../../../uve/src/lib/core/core.utils.js";
+import { useMemo as n, useCallback as o } from "react";
+import { getUVEState as u } from "../../../uve/src/lib/core/core.utils.js";
 import "../../../uve/src/internal/constants.js";
-import { initializeAnalytics as f } from "../internal/utils.js";
-const g = (o) => {
-  const t = f(o), i = l(null);
+import { initializeAnalytics as l } from "../internal/utils.js";
+const h = (r) => {
+  const t = n(() => l(r), [r.server, r.siteAuth]), e = n(() => !!u(), []);
   if (!t)
     throw new Error(
-      "Failed to initialize DotContentAnalytics. Please verify the required configuration (server and siteKey)."
+      "DotCMS Analytics: Failed to initialize. Please verify the required configuration (server and siteAuth)."
     );
-  const a = n(
-    (e, s = {}) => {
-      r() || t.track(e, {
-        ...s,
-        timestamp: (/* @__PURE__ */ new Date()).toISOString()
-      });
+  const a = o(
+    (i, c = {}) => {
+      e || t.track(i, c);
     },
-    [t]
-  ), c = n(() => {
-    if (!r()) {
-      const e = window.location.pathname;
-      e !== i.current && (i.current = e, t.pageView());
-    }
-  }, [t]);
+    [t, e]
+  ), s = o(
+    (i = {}) => {
+      e || t.pageView(i);
+    },
+    [t, e]
+  );
   return {
     track: a,
-    pageView: c
+    pageView: s
   };
 };
 export {
-  g as useContentAnalytics
+  h as useContentAnalytics
 };

package/lib/react/hook/useRouterTracker.d.ts

@@ -1,4 +1,4 @@
-import { DotCMSAnalytics } from '../../core/shared/dot-content-analytics.model';
+import { DotCMSAnalytics } from '../../core/shared/models';
 /**
  * Tracks page views on route changes using Next.js App Router signals.
  * - Fires a single pageView per unique path+search.

package/lib/react/internal/utils.d.ts

@@ -1,4 +1,4 @@
-import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../core/shared/dot-content-analytics.model';
+import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../core/shared/models';
 /**
  * Initializes analytics with explicit configuration.
  * Resets singleton if config changes.

package/lib/react/internal/utils.js

@@ -1,6 +1,6 @@
 import { initializeContentAnalytics as r } from "../../core/dot-content-analytics.js";
-let e, t;
-const s = (i) => (t && (t.server !== i.server || t.siteKey !== i.siteKey) && (e = void 0), e !== void 0 || (t = i, e = r(i)), e);
+let t, i;
+const s = (e) => (i && (i.server !== e.server || i.siteAuth !== e.siteAuth) && (t = void 0), t !== void 0 || (i = e, t = r(e)), t);
 export {
   s as initializeAnalytics
 };

package/lib/react/public-api.d.ts

@@ -1,3 +1,3 @@
-export type { DotCMSAnalyticsConfig } from '../core/shared/dot-content-analytics.model';
+export type { DotCMSAnalyticsConfig } from '../core/shared/models';
 export { DotContentAnalytics } from './components/DotContentAnalytics';
 export { useContentAnalytics } from './hook/useContentAnalytics';

package/lib/standalone.d.ts

@@ -1,5 +1,5 @@
-import { ANALYTICS_WINDOWS_KEY } from './core/shared/dot-content-analytics.constants';
-import { DotCMSAnalytics } from './core/shared/dot-content-analytics.model';
+import { ANALYTICS_WINDOWS_KEY } from './core/shared/constants';
+import { DotCMSAnalytics } from './core/shared/models';
 declare global {
     interface Window {
         [ANALYTICS_WINDOWS_KEY]: DotCMSAnalytics | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/analytics",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "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": {

package/uve/src/internal/constants.js

@@ -1,3 +1,8 @@
-import { UVEEventType as n } from "../../../types/src/lib/editor/public.js";
-import { onContentletHovered as r, onIframeScroll as o, onRequestBounds as t, onPageReload as E, onContentChanges as u } from "./events.js";
-n.CONTENT_CHANGES + "", n.PAGE_RELOAD + "", n.REQUEST_BOUNDS + "", n.IFRAME_SCROLL + "", n.CONTENTLET_HOVERED + "";
+import { UVEEventType as t } from "../../../types/src/lib/editor/public.js";
+import { onContentletHovered as e, onIframeScroll as o, onRequestBounds as r, onPageReload as E, onContentChanges as _ } from "./events.js";
+t.CONTENT_CHANGES + "", t.PAGE_RELOAD + "", t.REQUEST_BOUNDS + "", t.IFRAME_SCROLL + "", t.CONTENTLET_HOVERED + "";
+const N = "__dotAnalyticsActive__", T = "__dotAnalyticsCleanup";
+export {
+  N as ANALYTICS_WINDOWS_ACTIVE_KEY,
+  T as ANALYTICS_WINDOWS_CLEANUP_KEY
+};

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

@@ -1,37 +0,0 @@
-export declare const ANALYTICS_WINDOWS_KEY = "dotAnalytics";
-export declare const ANALYTICS_SOURCE_TYPE = "dotAnalytics";
-export declare const ANALYTICS_ENDPOINT = "/api/v1/analytics/content/event";
-/**
- * Event Types
- * Only two event types are supported in DotCMS Analytics
- */
-export declare const EVENT_TYPES: {
-    readonly PAGEVIEW: "pageview";
-    readonly TRACK: "track";
-};
-/**
- * Expected UTM parameter keys for campaign tracking
- */
-export declare const EXPECTED_UTM_KEYS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "utm_id"];
-/**
- * Session configuration constants
- */
-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: readonly ["click"];
-/**
- * The name of the analytics minified script.
- */
-export declare const ANALYTICS_MINIFIED_SCRIPT_NAME = "ca.min.js";

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

@@ -1,14 +0,0 @@
-const t = "dotAnalytics", E = t, _ = "/api/v1/analytics/content/event", c = {
-  PAGEVIEW: "pageview",
-  TRACK: "track"
-}, n = 30, s = "dot_analytics_session_id", S = "dot_analytics_user_id", T = ["click"];
-export {
-  T as ACTIVITY_EVENTS,
-  _ as ANALYTICS_ENDPOINT,
-  E as ANALYTICS_SOURCE_TYPE,
-  t as ANALYTICS_WINDOWS_KEY,
-  n as DEFAULT_SESSION_TIMEOUT_MINUTES,
-  c as EVENT_TYPES,
-  s as SESSION_STORAGE_KEY,
-  S as USER_ID_KEY
-};