@dotcms/analytics 1.1.1 → 1.2.0-next.10

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

@@ -0,0 +1,46 @@
+import { DotCMSAnalyticsConfig, EnrichedAnalyticsPayload, EnrichedTrackPayload } from '../../shared/models';
+/**
+ * Analytics plugin for tracking page views and custom events in DotCMS applications.
+ * This plugin handles:
+ * 1. Event structuring (deciding between predefined and custom events)
+ * 2. Building complete request bodies
+ * 3. Sending analytics data to the DotCMS server
+ * 4. Managing initialization and queue management
+ *
+ * The enricher plugin runs BEFORE this plugin and adds page/utm/custom data.
+ * This plugin receives enriched payloads and structures them into proper events.
+ *
+ * @param {DotCMSAnalyticsConfig} config - Configuration object containing API key, server URL,
+ *                                     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 with optional queue management
+     */
+    initialize: () => Promise<void>;
+    /**
+     * Track a page view event
+     * Receives enriched payload from the enricher plugin and structures it into a pageview event
+     */
+    page: ({ payload }: {
+        payload: EnrichedAnalyticsPayload;
+    }) => void;
+    /**
+     * Track a custom or predefined event
+     * Receives enriched payload from enricher plugin and structures it into proper event format.
+     *
+     * - content_impression → extracts from properties, combines with enriched page data
+     * - content_click → extracts from properties, combines with enriched page data
+     * - custom events → wraps properties in custom object
+     */
+    track: ({ payload }: {
+        payload: EnrichedTrackPayload;
+    }) => void;
+    /**
+     * Check if the plugin is loaded
+     */
+    loaded: () => boolean;
+};

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

@@ -0,0 +1,114 @@
+import { DotCMSPredefinedEventType as c } from "../../shared/constants/dot-analytics.constants.js";
+import { sendAnalyticsEvent as f } from "../../shared/http/dot-analytics.http.js";
+import { createAnalyticsQueue as w } from "../../shared/queue/dot-analytics.queue.utils.js";
+const _ = (l) => {
+  let u = !1;
+  const m = l.queue !== !1;
+  let d = null;
+  const y = (e) => {
+    const n = e.events[0], t = e.context;
+    m && d ? d.enqueue(n, t) : f(e, l);
+  };
+  return {
+    name: "dot-analytics",
+    config: l,
+    /**
+     * Initialize the plugin with optional queue management
+     */
+    initialize: () => (u = !0, m && (d = w(l), d.initialize()), Promise.resolve()),
+    /**
+     * Track a page view event
+     * Receives enriched payload from the enricher plugin and structures it into a pageview event
+     */
+    page: ({ payload: e }) => {
+      if (!u)
+        throw new Error("DotCMS Analytics: Plugin not initialized");
+      const { context: n, page: t, utm: p, custom: i, local_time: o } = e;
+      if (!t)
+        throw new Error("DotCMS Analytics: Missing required page data");
+      const v = {
+        context: n,
+        events: [
+          {
+            event_type: c.PAGEVIEW,
+            local_time: o,
+            data: {
+              page: t,
+              ...p && { utm: p },
+              ...i && { custom: i }
+            }
+          }
+        ]
+      };
+      y(v);
+    },
+    /**
+     * Track a custom or predefined event
+     * Receives enriched payload from enricher plugin and structures it into proper event format.
+     *
+     * - content_impression → extracts from properties, combines with enriched page data
+     * - content_click → extracts from properties, combines with enriched page data
+     * - custom events → wraps properties in custom object
+     */
+    track: ({ payload: e }) => {
+      if (!u)
+        throw new Error("DotCMS Analytics: Plugin not initialized");
+      const { event: n, properties: t, context: p, local_time: i } = e;
+      let o;
+      switch (n) {
+        case c.CONTENT_IMPRESSION: {
+          const E = t, { content: s, position: a } = E, { page: r } = e;
+          if (!s || !a || !r)
+            throw new Error("DotCMS Analytics: Missing required impression data");
+          o = {
+            event_type: c.CONTENT_IMPRESSION,
+            local_time: i,
+            data: {
+              content: s,
+              position: a,
+              page: r
+            }
+          };
+          break;
+        }
+        case c.CONTENT_CLICK: {
+          const E = t, { content: s, position: a, element: r } = E, { page: C } = e;
+          if (!s || !a || !r || !C)
+            throw new Error("DotCMS Analytics: Missing required click data");
+          o = {
+            event_type: c.CONTENT_CLICK,
+            local_time: i,
+            data: {
+              content: s,
+              position: a,
+              element: r,
+              page: C
+            }
+          };
+          break;
+        }
+        default: {
+          o = {
+            event_type: n,
+            local_time: i,
+            data: {
+              custom: t
+            }
+          };
+          break;
+        }
+      }
+      y({
+        context: p,
+        events: [o]
+      });
+    },
+    /**
+     * Check if the plugin is loaded
+     */
+    loaded: () => u
+  };
+};
+export {
+  _ as dotAnalytics
+};

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

@@ -0,0 +1,131 @@
+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";
+    readonly CONTENT_IMPRESSION: "content_impression";
+    readonly CONTENT_CLICK: "content_click";
+};
+/**
+ * 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"];
+/**
+ * Impression tracking configuration constants
+ */
+/**
+ * Default minimum percentage of element that must be visible (0.0 to 1.0)
+ */
+export declare const DEFAULT_IMPRESSION_VISIBILITY_THRESHOLD = 0.5;
+/**
+ * Default minimum time in milliseconds element must be visible
+ */
+export declare const DEFAULT_IMPRESSION_DWELL_MS = 750;
+/**
+ * Default maximum number of elements to track (performance limit)
+ */
+export declare const DEFAULT_IMPRESSION_MAX_NODES = 100;
+/**
+ * Default throttle time in milliseconds for intersection callbacks
+ */
+export declare const DEFAULT_IMPRESSION_THROTTLE_MS = 100;
+/**
+ * Default debounce time in milliseconds for MutationObserver
+ */
+export declare const DEFAULT_IMPRESSION_MUTATION_OBSERVER_DEBOUNCE_MS = 250;
+/**
+ * Default impression tracking configuration
+ */
+export declare const DEFAULT_IMPRESSION_CONFIG: {
+    readonly visibilityThreshold: 0.5;
+    readonly dwellMs: 750;
+    readonly maxNodes: 100;
+    readonly throttleMs: 100;
+};
+/**
+ * Event type for content impressions
+ * Must match DotCMSPredefinedEventType.CONTENT_IMPRESSION
+ */
+export declare const IMPRESSION_EVENT_TYPE = "content_impression";
+/**
+ * Event type for content clicks
+ * Must match DotCMSPredefinedEventType.CONTENT_CLICK
+ */
+export declare const CLICK_EVENT_TYPE = "content_click";
+/**
+ * Default debounce time in milliseconds for clicks
+ */
+export declare const DEFAULT_CLICK_THROTTLE_MS = 300;
+/**
+ * CSS selector for clickable elements to track
+ * Only clicks on <a> and <button> elements are tracked
+ */
+export declare const CLICKABLE_ELEMENTS_SELECTOR = "a, button";
+/**
+ * Session storage key for tracked impressions (deduplication)
+ */
+export declare const IMPRESSION_SESSION_KEY = "dot_analytics_impressions";
+/**
+ * CSS class selector for trackable contentlets
+ */
+export declare const ANALYTICS_CONTENTLET_CLASS = "dotcms-analytics-contentlet";

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

@@ -0,0 +1,52 @@
+const I = "/api/v1/analytics/content/event", c = {
+  PAGEVIEW: "pageview",
+  CONTENT_IMPRESSION: "content_impression",
+  CONTENT_CLICK: "content_click"
+}, s = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_term",
+  "utm_content"
+], o = 30, e = "dot_analytics_session_id", N = "dot_analytics_user_id", E = 15, _ = 5e3, L = ["click"], O = {
+  eventBatchSize: E,
+  // 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"
+], t = 0.5, T = 750, n = 100, S = 100, A = 250, C = {
+  visibilityThreshold: t,
+  dwellMs: T,
+  maxNodes: n,
+  throttleMs: S
+}, U = "content_impression", M = "content_click", D = 300, a = "a, button", R = "dotcms-analytics-contentlet";
+export {
+  L as ACTIVITY_EVENTS,
+  R as ANALYTICS_CONTENTLET_CLASS,
+  I as ANALYTICS_ENDPOINT,
+  i as ANALYTICS_JS_DEFAULT_PROPERTIES,
+  a as CLICKABLE_ELEMENTS_SELECTOR,
+  M as CLICK_EVENT_TYPE,
+  D as DEFAULT_CLICK_THROTTLE_MS,
+  C as DEFAULT_IMPRESSION_CONFIG,
+  T as DEFAULT_IMPRESSION_DWELL_MS,
+  n as DEFAULT_IMPRESSION_MAX_NODES,
+  A as DEFAULT_IMPRESSION_MUTATION_OBSERVER_DEBOUNCE_MS,
+  S as DEFAULT_IMPRESSION_THROTTLE_MS,
+  t as DEFAULT_IMPRESSION_VISIBILITY_THRESHOLD,
+  O as DEFAULT_QUEUE_CONFIG,
+  o as DEFAULT_SESSION_TIMEOUT_MINUTES,
+  c as DotCMSPredefinedEventType,
+  s as EXPECTED_UTM_KEYS,
+  U as IMPRESSION_EVENT_TYPE,
+  e as SESSION_STORAGE_KEY,
+  N 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-analytics.constants';

package/lib/core/shared/dot-analytics.logger.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Log level type for the DotLogger
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Log level constants for convenient usage
+ */
+export declare const LOG_LEVELS: {
+    readonly DEBUG: "debug";
+    readonly INFO: "info";
+    readonly WARN: "warn";
+    readonly ERROR: "error";
+};
+/**
+ * Custom logger for DotCMS SDK
+ * Provides structured logging with context identification and configurable log level filtering
+ *
+ * @example
+ * ```typescript
+ * const logger = new DotLogger('Analytics', 'Impression', 'info');
+ * logger.debug('This will not show'); // Below threshold
+ * logger.info('Tracker initialized'); // Shows
+ * logger.error('Failed to track'); // Shows
+ * ```
+ */
+export declare class DotLogger {
+    private readonly packageName;
+    private readonly context;
+    private readonly minLevel;
+    constructor(packageName: string, context: string, minLevel?: LogLevel);
+    /**
+     * Creates the formatted prefix for log messages
+     * Format: [DotCMS PackageName | Context] [LEVEL]
+     */
+    private getPrefix;
+    /**
+     * Checks if a log level should be displayed based on the minimum threshold
+     */
+    private shouldLog;
+    /**
+     * Log a DEBUG level message
+     * Used for detailed debugging information
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Log an INFO level message
+     * Used for general informational messages
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Log a WARN level message
+     * Used for warning messages that don't prevent operation
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Log an ERROR level message
+     * Always logs regardless of threshold for critical errors
+     */
+    error(...args: unknown[]): void;
+    /**
+     * Create a console group for organizing related log messages
+     * Respects the minimum log level threshold
+     */
+    group(label: string): void;
+    /**
+     * End the current console group
+     * Respects the minimum log level threshold
+     */
+    groupEnd(): void;
+    /**
+     * Start a timer with the given label
+     * Useful for performance measurements
+     */
+    time(label: string): void;
+    /**
+     * End a timer and log the elapsed time
+     * Useful for performance measurements
+     */
+    timeEnd(label: string): void;
+    /**
+     * Log a message (alias for info)
+     * Provided for backward compatibility
+     */
+    log(...args: unknown[]): void;
+}

package/lib/core/shared/dot-analytics.logger.js

@@ -0,0 +1,90 @@
+const o = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+class r {
+  constructor(e, i, t = "warn") {
+    this.packageName = e, this.context = i, this.minLevel = t;
+  }
+  /**
+   * Creates the formatted prefix for log messages
+   * Format: [DotCMS PackageName | Context] [LEVEL]
+   */
+  getPrefix(e) {
+    return `[DotCMS ${this.packageName} | ${this.context}] [${e.toUpperCase()}]`;
+  }
+  /**
+   * Checks if a log level should be displayed based on the minimum threshold
+   */
+  shouldLog(e) {
+    return o[e] >= o[this.minLevel];
+  }
+  /**
+   * Log a DEBUG level message
+   * Used for detailed debugging information
+   */
+  debug(...e) {
+    this.shouldLog("debug") && console.log(this.getPrefix("debug"), ...e);
+  }
+  /**
+   * Log an INFO level message
+   * Used for general informational messages
+   */
+  info(...e) {
+    this.shouldLog("info") && console.info(this.getPrefix("info"), ...e);
+  }
+  /**
+   * Log a WARN level message
+   * Used for warning messages that don't prevent operation
+   */
+  warn(...e) {
+    this.shouldLog("warn") && console.warn(this.getPrefix("warn"), ...e);
+  }
+  /**
+   * Log an ERROR level message
+   * Always logs regardless of threshold for critical errors
+   */
+  error(...e) {
+    console.error(this.getPrefix("error"), ...e);
+  }
+  /**
+   * Create a console group for organizing related log messages
+   * Respects the minimum log level threshold
+   */
+  group(e) {
+    this.shouldLog("debug") && console.group(`${this.getPrefix("debug")} ${e}`);
+  }
+  /**
+   * End the current console group
+   * Respects the minimum log level threshold
+   */
+  groupEnd() {
+    this.shouldLog("debug") && console.groupEnd();
+  }
+  /**
+   * Start a timer with the given label
+   * Useful for performance measurements
+   */
+  time(e) {
+    this.shouldLog("debug") && console.time(`${this.getPrefix("debug")} ${e}`);
+  }
+  /**
+   * End a timer and log the elapsed time
+   * Useful for performance measurements
+   */
+  timeEnd(e) {
+    this.shouldLog("debug") && console.timeEnd(`${this.getPrefix("debug")} ${e}`);
+  }
+  /**
+   * Log a message (alias for info)
+   * Provided for backward compatibility
+   */
+  log(...e) {
+    this.info(...e);
+  }
+}
+export {
+  r as DotLogger
+};

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

@@ -0,0 +1,9 @@
+import { DotCMSAnalyticsConfig, DotCMSAnalyticsRequestBody } from '../models';
+/**
+ * Send analytics events to the server using fetch API
+ * @param payload - The event payload data
+ * @param config - The analytics configuration
+ * @param keepalive - Use keepalive mode for page unload scenarios (default: false)
+ * @returns A promise that resolves when the request is complete
+ */
+export declare const sendAnalyticsEvent: (payload: DotCMSAnalyticsRequestBody, config: DotCMSAnalyticsConfig, keepalive?: boolean) => Promise<void>;

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

@@ -0,0 +1,34 @@
+import { ANALYTICS_ENDPOINT as f } from "../constants/dot-analytics.constants.js";
+import { createPluginLogger as T } from "../utils/dot-analytics.utils.js";
+const h = async (n, a, i = !1) => {
+  const r = T("HTTP", a), c = `${a.server}${f}`, g = JSON.stringify(n);
+  r.info(`Sending ${n.events.length} event(s)${i ? " (keepalive)" : ""}`, {
+    payload: n
+  });
+  try {
+    const e = {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: g
+    };
+    if (i) {
+      e.keepalive = !0, e.credentials = "omit", fetch(c, e);
+      return;
+    }
+    const t = await fetch(c, e);
+    if (!t.ok) {
+      const p = t.statusText || "Unknown Error", o = `HTTP ${t.status}: ${p}`;
+      try {
+        const s = await t.json();
+        s.message ? r.warn(`${s.message} (${o})`) : r.warn(`${o} - No error message in response`);
+      } catch (s) {
+        r.warn(`${o} - Failed to parse error response:`, s);
+      }
+    }
+  } catch (e) {
+    r.error("Error sending event:", e);
+  }
+};
+export {
+  h as sendAnalyticsEvent
+};