@dotcms/analytics 1.2.0 → 1.2.1

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

@@ -0,0 +1,62 @@
+import { DotCMSAnalyticsConfig, DotCMSContentImpressionPayload } from '../../shared/models';
+/** Callback function for impression events */
+export type ImpressionCallback = (eventName: string, payload: DotCMSContentImpressionPayload) => void;
+/** Subscription object with unsubscribe method */
+export interface ImpressionSubscription {
+    unsubscribe: () => void;
+}
+/**
+ * Tracks content impressions using IntersectionObserver and dwell time.
+ * Emits events through subscriptions when impressions are detected.
+ */
+export declare class DotCMSImpressionTracker {
+    private observer;
+    private mutationObserver;
+    private elementImpressionStates;
+    private sessionTrackedImpressions;
+    private impressionConfig;
+    private currentPagePath;
+    private subscribers;
+    private logger;
+    constructor(config: DotCMSAnalyticsConfig);
+    /**
+     * Subscribe to impression events
+     * @param callback - Function called when impression is detected
+     * @returns Subscription object with unsubscribe method
+     */
+    onImpression(callback: ImpressionCallback): ImpressionSubscription;
+    /** Notifies all subscribers of an impression */
+    private notifySubscribers;
+    /** Merges user config with defaults */
+    private resolveImpressionConfig;
+    /** Initializes tracking: sets up observers, finds contentlets, handles visibility/navigation */
+    initialize(): void;
+    /** Sets up IntersectionObserver with configured visibility threshold */
+    private initializeIntersectionObserver;
+    /** Finds contentlets in DOM, validates them, and starts observing (respects maxNodes limit) */
+    private findAndObserveContentletElements;
+    /** Watches for new contentlets added to DOM (debounced for performance) */
+    private initializeDynamicContentDetector;
+    /** Cancels all timers when page is hidden (prevents false impressions) */
+    private initializePageVisibilityHandler;
+    /** Resets tracking on SPA navigation (listens to pushState, replaceState, popstate) */
+    private initializePageNavigationHandler;
+    /** Handles visibility changes: starts timer on enter, cancels on exit */
+    private processIntersectionChanges;
+    /** Starts dwell timer; fires impression if element still visible when timer expires */
+    private startImpressionDwellTimer;
+    /** Cancels active dwell timer (element left viewport before dwell time) */
+    private cancelImpressionDwellTimer;
+    /** Fires impression event with content & position data (page data added by enricher plugin) */
+    private trackAndSendImpression;
+    /** Returns skip reason if element is hidden/too small, null if trackable */
+    private shouldSkipElement;
+    /** Post-dwell check: verifies element still meets visibility threshold */
+    private isElementStillVisible;
+    /** Checks if impression already fired in current page session */
+    private hasBeenTrackedInSession;
+    /** Marks impression as tracked (prevents duplicates in same page session) */
+    private markImpressionAsTracked;
+    /** Cleanup: disconnects observers, clears timers and state */
+    cleanup(): void;
+}

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

@@ -0,0 +1,202 @@
+import { getUVEState as m } from "../../../../uve/src/lib/core/core.utils.js";
+import "../../../../uve/src/internal/constants.js";
+import { getViewportMetrics as d, isElementMeetingVisibilityThreshold as u } from "./dot-analytics.impression.utils.js";
+import { DEFAULT_IMPRESSION_CONFIG as l, IMPRESSION_EVENT_TYPE as g } from "../../shared/constants/dot-analytics.constants.js";
+import { createPluginLogger as p, isBrowser as a, INITIAL_SCAN_DELAY_MS as f, findContentlets as b, extractContentletIdentifier as c, createContentletObserver as v, extractContentletData as I } from "../../shared/utils/dot-analytics.utils.js";
+class E {
+  constructor(e) {
+    this.observer = null, this.mutationObserver = null, this.elementImpressionStates = /* @__PURE__ */ new Map(), this.sessionTrackedImpressions = /* @__PURE__ */ new Set(), this.currentPagePath = "", this.subscribers = /* @__PURE__ */ new Set(), this.logger = p("Impression", e), this.impressionConfig = this.resolveImpressionConfig(e.impressions);
+  }
+  /**
+   * Subscribe to impression events
+   * @param callback - Function called when impression is detected
+   * @returns Subscription object with unsubscribe method
+   */
+  onImpression(e) {
+    return this.subscribers.add(e), {
+      unsubscribe: () => {
+        this.subscribers.delete(e);
+      }
+    };
+  }
+  /** Notifies all subscribers of an impression */
+  notifySubscribers(e, i) {
+    this.subscribers.forEach((t) => {
+      try {
+        t(e, i);
+      } catch (s) {
+        this.logger.error("Error in impression subscriber:", s);
+      }
+    });
+  }
+  /** Merges user config with defaults */
+  resolveImpressionConfig(e) {
+    return typeof e != "object" || e === null ? { ...l } : {
+      ...l,
+      ...e
+    };
+  }
+  /** Initializes tracking: sets up observers, finds contentlets, handles visibility/navigation */
+  initialize() {
+    if (a()) {
+      if (m()) {
+        this.logger.warn("Impression tracking disabled in editor mode");
+        return;
+      }
+      this.initializeIntersectionObserver(), typeof window < "u" && setTimeout(() => {
+        this.logger.debug("Running initial scan after timeout..."), this.findAndObserveContentletElements();
+      }, f), this.initializeDynamicContentDetector(), this.initializePageVisibilityHandler(), this.initializePageNavigationHandler(), this.logger.info("Impression tracking initialized with config:", this.impressionConfig);
+    }
+  }
+  /** Sets up IntersectionObserver with configured visibility threshold */
+  initializeIntersectionObserver() {
+    const e = {
+      root: null,
+      // Use viewport as root
+      rootMargin: "0px",
+      threshold: this.impressionConfig.visibilityThreshold
+    };
+    this.observer = new IntersectionObserver((i) => {
+      this.processIntersectionChanges(i);
+    }, e);
+  }
+  /** Finds contentlets in DOM, validates them, and starts observing (respects maxNodes limit) */
+  findAndObserveContentletElements() {
+    if (!this.observer) return;
+    const e = b();
+    if (e.length === 0) {
+      this.logger.warn("No contentlets found to track");
+      return;
+    }
+    const i = Math.min(e.length, this.impressionConfig.maxNodes);
+    let t = 0;
+    for (let s = 0; s < i; s++) {
+      const n = e[s], r = c(n);
+      if (r) {
+        const o = this.shouldSkipElement(n);
+        if (o) {
+          this.logger.debug(`Skipping element ${r} (${o})`);
+          continue;
+        }
+        this.elementImpressionStates.has(r) || (n.dataset.dotAnalyticsDomIndex || (n.dataset.dotAnalyticsDomIndex = String(s)), this.observer.observe(n), this.elementImpressionStates.set(r, {
+          timer: null,
+          visibleSince: null,
+          tracked: this.hasBeenTrackedInSession(r),
+          element: n
+        }), t++);
+      }
+    }
+    this.logger.info(`Observing ${t} contentlets`), e.length > i && this.logger.warn(
+      `${e.length - i} contentlets not tracked (maxNodes limit: ${this.impressionConfig.maxNodes})`
+    );
+  }
+  /** Watches for new contentlets added to DOM (debounced for performance) */
+  initializeDynamicContentDetector() {
+    a() && (this.mutationObserver = v(() => {
+      this.findAndObserveContentletElements();
+    }), this.logger.info("MutationObserver enabled for dynamic content detection"));
+  }
+  /** Cancels all timers when page is hidden (prevents false impressions) */
+  initializePageVisibilityHandler() {
+    document.addEventListener("visibilitychange", () => {
+      document.visibilityState === "hidden" && (this.elementImpressionStates.forEach((e) => {
+        e.timer !== null && (window.clearTimeout(e.timer), e.timer = null, e.visibleSince = null);
+      }), this.logger.warn("Page hidden, all impression timers cancelled"));
+    });
+  }
+  /** Resets tracking on SPA navigation (listens to pushState, replaceState, popstate) */
+  initializePageNavigationHandler() {
+    this.currentPagePath = window.location.pathname;
+    const e = () => {
+      const s = window.location.pathname;
+      s !== this.currentPagePath && (this.logger.warn(
+        `Navigation detected (${this.currentPagePath} → ${s}), resetting impression tracking`
+      ), this.currentPagePath = s, this.sessionTrackedImpressions.clear(), this.elementImpressionStates.forEach((n) => {
+        n.timer !== null && (window.clearTimeout(n.timer), n.timer = null, n.visibleSince = null);
+      }), this.elementImpressionStates.clear());
+    };
+    window.addEventListener("popstate", e);
+    const i = history.pushState, t = history.replaceState;
+    history.pushState = function(...s) {
+      i.apply(this, s), e();
+    }, history.replaceState = function(...s) {
+      t.apply(this, s), e();
+    };
+  }
+  /** Handles visibility changes: starts timer on enter, cancels on exit */
+  processIntersectionChanges(e) {
+    document.visibilityState === "visible" && e.forEach((i) => {
+      const t = i.target, s = c(t);
+      s && (i.isIntersecting ? this.startImpressionDwellTimer(s, t) : this.cancelImpressionDwellTimer(s));
+    });
+  }
+  /** Starts dwell timer; fires impression if element still visible when timer expires */
+  startImpressionDwellTimer(e, i) {
+    const t = this.elementImpressionStates.get(e);
+    t && (t.tracked || this.hasBeenTrackedInSession(e) || t.timer === null && document.visibilityState === "visible" && (t.visibleSince = Date.now(), t.element = i, t.timer = window.setTimeout(() => {
+      this.isElementStillVisible(i) ? this.trackAndSendImpression(e, i) : (this.logger.warn(
+        `Dwell timer expired for ${e} but element no longer visible, skipping impression`
+      ), t.timer = null, t.visibleSince = null);
+    }, this.impressionConfig.dwellMs), this.logger.debug(
+      `Started dwell timer for ${e} (${this.impressionConfig.dwellMs}ms)`
+    )));
+  }
+  /** Cancels active dwell timer (element left viewport before dwell time) */
+  cancelImpressionDwellTimer(e) {
+    const i = this.elementImpressionStates.get(e);
+    !i || i.timer === null || (window.clearTimeout(i.timer), i.timer = null, i.visibleSince = null, this.logger.debug(`Cancelled dwell timer for ${e}`));
+  }
+  /** Fires impression event with content & position data (page data added by enricher plugin) */
+  trackAndSendImpression(e, i) {
+    const t = this.elementImpressionStates.get(e);
+    if (!t) return;
+    const s = t.visibleSince ? Date.now() - t.visibleSince : 0, n = I(i), r = d(i), o = parseInt(i.dataset.dotAnalyticsDomIndex || "-1", 10), h = {
+      content: {
+        identifier: n.identifier,
+        inode: n.inode,
+        title: n.title,
+        content_type: n.contentType
+      },
+      position: {
+        viewport_offset_pct: r.offsetPercentage,
+        dom_index: o
+      }
+    };
+    this.notifySubscribers(g, h), this.markImpressionAsTracked(e), t.timer = null, t.visibleSince = null, t.tracked = !0, this.observer && this.observer.unobserve(i), this.logger.info(
+      `Fired impression for ${e} (dwell: ${s}ms) - element unobserved`,
+      n
+    );
+  }
+  /** Returns skip reason if element is hidden/too small, null if trackable */
+  shouldSkipElement(e) {
+    const i = e.getBoundingClientRect(), t = window.getComputedStyle(e);
+    if (i.height === 0 || i.width === 0)
+      return `zero dimensions: ${i.width}x${i.height}`;
+    const s = 10;
+    return i.height < s || i.width < s ? `too small: ${i.width}x${i.height} (minimum: ${s}px)` : t.visibility === "hidden" ? "visibility: hidden" : parseFloat(t.opacity) === 0 ? "opacity: 0" : t.display === "none" ? "display: none" : null;
+  }
+  /** Post-dwell check: verifies element still meets visibility threshold */
+  isElementStillVisible(e) {
+    return document.visibilityState !== "visible" ? !1 : u(
+      e,
+      this.impressionConfig.visibilityThreshold
+    );
+  }
+  /** Checks if impression already fired in current page session */
+  hasBeenTrackedInSession(e) {
+    return this.sessionTrackedImpressions.has(e);
+  }
+  /** Marks impression as tracked (prevents duplicates in same page session) */
+  markImpressionAsTracked(e) {
+    this.sessionTrackedImpressions.add(e);
+  }
+  /** Cleanup: disconnects observers, clears timers and state */
+  cleanup() {
+    this.observer && (this.observer.disconnect(), this.observer = null), this.mutationObserver && (this.mutationObserver.disconnect(), this.mutationObserver = null), this.elementImpressionStates.forEach((e) => {
+      e.timer !== null && window.clearTimeout(e.timer);
+    }), this.elementImpressionStates.clear(), this.subscribers.clear(), this.logger.info("Impression tracking cleaned up");
+  }
+}
+export {
+  E as DotCMSImpressionTracker
+};

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

@@ -0,0 +1,40 @@
+import { AnalyticsInstance } from 'analytics';
+import { DotCMSAnalyticsConfig } from '../../shared/models';
+/**
+ * Impression Plugin for DotAnalytics
+ * Handles automatic tracking of content visibility and impressions.
+ *
+ * This plugin initializes the impression tracker which:
+ * - Uses IntersectionObserver to detect when contentlets are visible
+ * - Tracks dwell time (how long elements are visible)
+ * - Fires 'content-impression' events via instance.track()
+ * - Deduplicates impressions per session
+ *
+ * Plugin execution in Analytics.js pipeline:
+ * 1. Identity Plugin - Injects context
+ * 2. Enricher Plugin - Enriches event data
+ * 3. Main Plugin - Sends to queue/server
+ * 4. Impression Plugin - Runs independently, fires events via instance.track()
+ *
+ * Note: This plugin is only registered if config.impressions is enabled.
+ * See getEnhancedTrackingPlugins() for conditional loading logic.
+ *
+ * @param {DotCMSAnalyticsConfig} config - Configuration with impressions settings
+ * @returns {Object} Plugin object with lifecycle methods
+ */
+export declare const dotAnalyticsImpressionPlugin: (config: DotCMSAnalyticsConfig) => {
+    name: string;
+    /**
+     * Initialize impression tracking
+     * Called when Analytics.js initializes the plugin with instance context
+     * @param instance - Analytics.js instance with track method
+     */
+    initialize: ({ instance }: {
+        instance: AnalyticsInstance;
+    }) => Promise<void>;
+    /**
+     * Setup cleanup handlers when plugin is loaded
+     * Called after Analytics.js completes plugin loading
+     */
+    loaded: () => boolean;
+};

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,129 @@
+import { DotCMSPredefinedEventType as r } from "../../shared/constants/dot-analytics.constants.js";
+import { sendAnalyticsEvent as N } from "../../shared/http/dot-analytics.http.js";
+import { createAnalyticsQueue as w } from "../../shared/queue/dot-analytics.queue.utils.js";
+const _ = (d) => {
+  let u = !1;
+  const m = d.queue !== !1;
+  let p = null;
+  const v = (e) => {
+    const c = e.events[0], t = e.context;
+    m && p ? p.enqueue(c, t) : N(e, d);
+  };
+  return {
+    name: "dot-analytics",
+    config: d,
+    /**
+     * Initialize the plugin with optional queue management
+     */
+    initialize: () => (u = !0, m && (p = w(d), p.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: c, page: t, utm: E, custom: s, local_time: a } = e;
+      if (!t)
+        throw new Error("DotCMS Analytics: Missing required page data");
+      const y = {
+        context: c,
+        events: [
+          {
+            event_type: r.PAGEVIEW,
+            local_time: a,
+            data: {
+              page: t,
+              ...E && { utm: E },
+              ...s && { custom: s }
+            }
+          }
+        ]
+      };
+      v(y);
+    },
+    /**
+     * 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: c, properties: t, context: E, local_time: s } = e;
+      let a;
+      switch (c) {
+        case r.CONTENT_IMPRESSION: {
+          const l = t, { content: n, position: i } = l, { page: o } = e;
+          if (!n || !i || !o)
+            throw new Error("DotCMS Analytics: Missing required impression data");
+          a = {
+            event_type: r.CONTENT_IMPRESSION,
+            local_time: s,
+            data: {
+              content: n,
+              position: i,
+              page: o
+            }
+          };
+          break;
+        }
+        case r.CONTENT_CLICK: {
+          const l = t, { content: n, position: i, element: o } = l, { page: C } = e;
+          if (!n || !i || !o || !C)
+            throw new Error("DotCMS Analytics: Missing required click data");
+          a = {
+            event_type: r.CONTENT_CLICK,
+            local_time: s,
+            data: {
+              content: n,
+              position: i,
+              element: o,
+              page: C
+            }
+          };
+          break;
+        }
+        case r.CONVERSION: {
+          const l = t, { name: n, custom: i } = l, { page: o } = e;
+          if (!n || !o)
+            throw new Error("DotCMS Analytics: Missing required conversion data");
+          a = {
+            event_type: r.CONVERSION,
+            local_time: s,
+            data: {
+              conversion: { name: n },
+              page: o,
+              ...i && { custom: i }
+            }
+          };
+          break;
+        }
+        default: {
+          a = {
+            event_type: c,
+            local_time: s,
+            data: {
+              custom: t
+            }
+          };
+          break;
+        }
+      }
+      v({
+        context: E,
+        events: [a]
+      });
+    },
+    /**
+     * 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,9 @@ 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";
+    readonly CONVERSION: "conversion";
 };
 /**
  * Type for structured events
@@ -68,3 +71,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";