@dotcms/analytics 1.2.0-next.1 → 1.2.0-next.10

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

@@ -0,0 +1,27 @@
+import { DotCMSImpressionTracker as t } from "./dot-analytics.impression-tracker.js";
+import { createPluginLogger as a, isBrowser as p, setupPluginCleanup as u } from "../../shared/utils/dot-analytics.utils.js";
+const g = (n) => {
+  let i = null, e = null;
+  const r = a("Impression", n);
+  return {
+    name: "dot-analytics-impression",
+    /**
+     * Initialize impression tracking
+     * Called when Analytics.js initializes the plugin with instance context
+     * @param instance - Analytics.js instance with track method
+     */
+    initialize: ({ instance: s }) => n.impressions ? (i = new t(n), i.initialize(), e = i.onImpression((o, l) => {
+      s.track(o, l);
+    }), r.info("Impression tracking plugin initialized"), Promise.resolve()) : (r.info("Impression tracking disabled (config.impressions not set)"), Promise.resolve()),
+    /**
+     * Setup cleanup handlers when plugin is loaded
+     * Called after Analytics.js completes plugin loading
+     */
+    loaded: () => (p() && i && u(() => {
+      e && (e.unsubscribe(), e = null), i && (i.cleanup(), i = null, r.info("Impression tracking cleaned up on page unload"));
+    }), !0)
+  };
+};
+export {
+  g as dotAnalyticsImpressionPlugin
+};

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

@@ -0,0 +1,26 @@
+import { ViewportMetrics } from '../../shared/models';
+/**
+ * Calculates the visibility ratio of an element in the viewport
+ * @param element - The HTML element to check
+ * @returns A number between 0 and 1 representing the visible percentage
+ */
+export declare function calculateElementVisibilityRatio(element: HTMLElement): number;
+/**
+ * Calculates the offset percentage of an element from the top of the viewport
+ * @param element - The HTML element to check
+ * @returns Percentage value (can be negative if above viewport)
+ */
+export declare function calculateViewportOffset(element: HTMLElement): number;
+/**
+ * Checks if an element meets a specific visibility threshold
+ * @param element - The HTML element to check
+ * @param threshold - The required visibility ratio (0.0 to 1.0)
+ * @returns True if the element meets or exceeds the threshold
+ */
+export declare function isElementMeetingVisibilityThreshold(element: HTMLElement, threshold: number): boolean;
+/**
+ * Gets comprehensive viewport metrics for an element
+ * @param element - The HTML element to analyze
+ * @returns Object containing offset percentage and visibility ratio
+ */
+export declare function getViewportMetrics(element: HTMLElement): ViewportMetrics;

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

@@ -0,0 +1,27 @@
+function s(e) {
+  const t = e.getBoundingClientRect(), i = window.innerHeight || document.documentElement.clientHeight, n = window.innerWidth || document.documentElement.clientWidth, o = Math.min(t.bottom, i) - Math.max(t.top, 0), c = Math.min(t.right, n) - Math.max(t.left, 0);
+  if (o <= 0 || c <= 0)
+    return 0;
+  const l = o * c, r = t.height * t.width;
+  return r > 0 ? l / r : 0;
+}
+function h(e) {
+  const t = e.getBoundingClientRect(), i = window.innerHeight || document.documentElement.clientHeight, n = t.top / i * 100;
+  return Math.round(n * 100) / 100;
+}
+function a(e, t) {
+  return s(e) >= t;
+}
+function u(e) {
+  const t = s(e);
+  return {
+    offsetPercentage: h(e),
+    visibilityRatio: t
+  };
+}
+export {
+  s as calculateElementVisibilityRatio,
+  h as calculateViewportOffset,
+  u as getViewportMetrics,
+  a as isElementMeetingVisibilityThreshold
+};

package/lib/core/plugin/impression/index.d.ts

@@ -0,0 +1,2 @@
+export * from './dot-analytics.impression.plugin';
+export * from './dot-analytics.impression.utils';

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-content-analytics.constants.d.ts → dot-analytics.constants.d.ts}

@@ -7,6 +7,8 @@ export declare const ANALYTICS_ENDPOINT = "/api/v1/analytics/content/event";
  */
 export declare const DotCMSPredefinedEventType: {
     readonly PAGEVIEW: "pageview";
+    readonly CONTENT_IMPRESSION: "content_impression";
+    readonly CONTENT_CLICK: "content_click";
 };
 /**
  * Type for structured events
@@ -68,3 +70,62 @@ export declare const ANALYTICS_MINIFIED_SCRIPT_NAME = "ca.min.js";
  * 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

@@ -1,4 +1,4 @@
 /**
  * Central export point for all DotCMS Analytics constants
  */
-export * from './dot-content-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
+};

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

@@ -89,7 +89,7 @@ export interface DotCMSEventUtmData {
     id?: string;
 }
 /**
- * Page data structure for DotCMS analytics.
+ * Page data structure for DotCMS analytics (used in pageview events).
  * Contains comprehensive information about the current page and its context
  * within the DotCMS environment.
  */
@@ -101,3 +101,41 @@ export type DotCMSEventPageData = Pick<DotCMSBrowserData, 'url' | 'doc_path' | '
     /** Persona identifier */
     persona?: string;
 };
+/**
+ * Minimal page data for content impression events.
+ * Contains only essential page information (title and url) to keep payload lightweight.
+ */
+export type DotCMSContentImpressionPageData = Pick<DotCMSEventPageData, 'title' | 'url'>;
+/**
+ * Data structure for content impression events.
+ * Tracks when a contentlet becomes visible in the viewport.
+ */
+export interface DotCMSImpressionEventData {
+    /** Contentlet identification data extracted from data-dot-analytics-* attributes */
+    contentlet: {
+        /** Unique identifier of the contentlet */
+        identifier: string;
+        /** Inode of the contentlet */
+        inode: string;
+        /** Content type name */
+        contentType: string;
+        /** Title of the contentlet */
+        title: string;
+        /** Base type of the contentlet (e.g., CONTENT, WIDGET) */
+        baseType: string;
+    };
+    /** Viewport position and visibility metrics */
+    viewport: {
+        /** Percentage offset from top of viewport (0-100) */
+        offsetPercentage: number;
+        /** Percentage of element visible in viewport (0-1) */
+        visibilityRatio: number;
+    };
+    /** Timing information about the impression */
+    timing: {
+        /** Time in milliseconds the element was continuously visible */
+        dwellTime: number;
+        /** ISO 8601 timestamp when the impression was fired */
+        timestamp: string;
+    };
+}