@dotcms/analytics 1.1.1 → 1.2.0-next.10

package/lib/core/{shared/dot-content-analytics.activity-tracker.js → plugin/identity/dot-analytics.identity.activity-tracker.js}

@@ -1,5 +1,6 @@
-import { DEFAULT_SESSION_TIMEOUT_MINUTES as c, ACTIVITY_EVENTS as r } from "./dot-content-analytics.constants.js";
-class o {
+import { ANALYTICS_WINDOWS_ACTIVE_KEY as a, ANALYTICS_WINDOWS_CLEANUP_KEY as o } from "../../../../uve/src/internal/constants.js";
+import { DEFAULT_SESSION_TIMEOUT_MINUTES as r, ACTIVITY_EVENTS as l } from "../../shared/constants/dot-analytics.constants.js";
+class v {
   constructor() {
     this.activityListeners = [], this.lastActivityTime = Date.now(), this.inactivityTimer = null, this.isThrottled = !1, this.config = null, this.ACTIVITY_THROTTLE_MS = 1e3;
   }
@@ -11,24 +12,11 @@ class o {
     this.lastActivityTime = Date.now(), this.inactivityTimer && clearTimeout(this.inactivityTimer), this.inactivityTimer = setTimeout(
       () => {
         var i;
-        (i = this.config) != null && i.debug && console.warn("DotCMS Analytics: User became inactive after timeout"), this.inactivityTimer = null;
+        (i = this.config) != null && i.debug && console.warn("DotCMS Analytics [Activity]: User became inactive after timeout"), this.inactivityTimer = null;
       },
-      c * 60 * 1e3
+      r * 60 * 1e3
     );
   }
-  /**
-   * Checks if user has been inactive
-   */
-  isUserInactive() {
-    const i = c * 60 * 1e3;
-    return Date.now() - this.lastActivityTime > i;
-  }
-  /**
-   * Gets last activity time
-   */
-  getLastActivity() {
-    return this.lastActivityTime;
-  }
   /**
    * Updates session activity with throttling
    */
@@ -44,17 +32,19 @@ class o {
     if (this.cleanup(), this.config = i, typeof window > "u")
       return;
     const s = () => this.updateSessionActivity();
-    r.forEach((a) => {
-      window.addEventListener(a, s, { passive: !0 }), this.activityListeners.push(
-        () => window.removeEventListener(a, s)
+    l.forEach((c) => {
+      window.addEventListener(c, s, { passive: !0 }), this.activityListeners.push(
+        () => window.removeEventListener(c, s)
       );
     });
     const n = () => {
-      document.visibilityState === "visible" && (this.updateSessionActivity(), i.debug && console.warn("DotCMS Analytics: User returned to tab, session reactivated"));
+      document.visibilityState === "visible" && (this.updateSessionActivity(), i.debug && console.warn(
+        "DotCMS Analytics [Activity]: User returned to tab, session reactivated"
+      ));
     };
     document.addEventListener("visibilitychange", n), this.activityListeners.push(
       () => document.removeEventListener("visibilitychange", n)
-    ), this.updateActivityTime(), i.debug && console.warn("DotCMS Analytics: Activity tracking initialized");
+    ), this.updateActivityTime(), i.debug && console.warn("DotCMS Analytics [Activity]: Activity tracking initialized");
   }
   /**
    * Cleans up all activity tracking listeners
@@ -62,25 +52,16 @@ class o {
   cleanup() {
     this.activityListeners.forEach((i) => i()), this.activityListeners = [], this.inactivityTimer && (clearTimeout(this.inactivityTimer), this.inactivityTimer = null), this.config = null;
   }
-  /**
-   * Gets session information for debugging
-   */
-  getSessionInfo() {
-    return {
-      lastActivity: this.getLastActivity(),
-      isActive: !this.isUserInactive()
-    };
-  }
 }
-const t = new o(), h = () => {
+const t = new v(), d = () => {
   t.updateSessionActivity();
-}, l = (e) => {
+}, u = (e) => {
   t.initialize(e);
-}, T = () => {
-  t.cleanup();
+}, y = () => {
+  t.cleanup(), typeof window < "u" && (window[a] = !1, window[o] = void 0, window.dispatchEvent(new CustomEvent("dotcms:analytics:cleanup")));
 };
 export {
-  T as cleanupActivityTracking,
-  l as initializeActivityTracking,
-  h as updateSessionActivity
+  y as cleanupActivityTracking,
+  u as initializeActivityTracking,
+  d as updateSessionActivity
 };

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

@@ -1,4 +1,4 @@
-import { DotCMSAnalyticsConfig, DotCMSAnalyticsHookParams } from '../../shared/dot-content-analytics.model';
+import { AnalyticsBaseParams, DotCMSAnalyticsConfig } from '../../shared/models';
 /**
  * Identity Plugin for DotAnalytics
  * Handles user ID generation, session management, and activity tracking.
@@ -20,24 +20,15 @@ export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig)
      */
     initialize: () => Promise<void>;
     /**
-     * Inject identity context into page events
+     * Inject identity context into page events and updates session activity for session management
      * This runs BEFORE the enricher plugin
      */
-    pageStart: ({ payload }: DotCMSAnalyticsHookParams) => {
-        context: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext;
-        type: string;
-        properties: {
-            title: string;
-            url: string;
-            path: string;
-            hash: string;
-            search: string;
-            width: number;
-            height: number;
-            referrer?: string;
-        };
+    pageStart: ({ payload }: AnalyticsBaseParams) => {
+        context: import('../../shared/models').DotCMSAnalyticsEventContext;
+        type: "page" | "track";
+        properties: Record<string, unknown>;
         options: Record<string, unknown>;
-        userId: string | null;
+        userId: string;
         anonymousId: string;
         meta: {
             rid: string;
@@ -46,24 +37,15 @@ export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig)
         };
     };
     /**
-     * Inject identity context into track events
+     * Inject identity context into track events and updates session activity for session management
      * This runs BEFORE the enricher plugin
      */
-    trackStart: ({ payload }: DotCMSAnalyticsHookParams) => {
-        context: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext;
-        type: string;
-        properties: {
-            title: string;
-            url: string;
-            path: string;
-            hash: string;
-            search: string;
-            width: number;
-            height: number;
-            referrer?: string;
-        };
+    trackStart: ({ payload }: AnalyticsBaseParams) => {
+        context: import('../../shared/models').DotCMSAnalyticsEventContext;
+        type: "page" | "track";
+        properties: Record<string, unknown>;
         options: Record<string, unknown>;
-        userId: string | null;
+        userId: string;
         anonymousId: string;
         meta: {
             rid: string;

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

@@ -1,40 +1,42 @@
-import { getAnalyticsContext as i } from "../../shared/dot-content-analytics.utils.js";
-import { cleanupActivityTracking as r, initializeActivityTracking as o } from "../../shared/dot-content-analytics.activity-tracker.js";
-const c = (t) => ({
+import { cleanupActivityTracking as n, updateSessionActivity as r, initializeActivityTracking as a } from "./dot-analytics.identity.activity-tracker.js";
+import { getAnalyticsContext as o } from "../../shared/utils/dot-analytics.utils.js";
+const s = (t) => ({
   name: "dot-analytics-identity",
   /**
    * Initialize the identity plugin
    * Sets up activity tracking for session management
    */
-  initialize: () => (o(t), Promise.resolve()),
+  initialize: () => (a(t), Promise.resolve()),
   /**
-   * Inject identity context into page events
+   * Inject identity context into page events and updates session activity for session management
    * This runs BEFORE the enricher plugin
    */
   pageStart: ({ payload: e }) => {
-    const n = i(t);
+    r();
+    const i = o(t);
     return {
       ...e,
-      context: n
+      context: i
     };
   },
   /**
-   * Inject identity context into track events
+   * Inject identity context into track events and updates session activity for session management
    * This runs BEFORE the enricher plugin
    */
   trackStart: ({ payload: e }) => {
-    const n = i(t);
+    r();
+    const i = o(t);
     return {
       ...e,
-      context: n
+      context: i
     };
   },
   /**
    * Clean up on plugin unload
    * Sets up cleanup handlers for activity tracking
    */
-  loaded: () => (typeof window < "u" && (window.addEventListener("beforeunload", r), window.addEventListener("pagehide", r)), !0)
+  loaded: () => (typeof window < "u" && (window.addEventListener("beforeunload", n), window.addEventListener("pagehide", n)), !0)
 });
 export {
-  c as dotAnalyticsIdentityPlugin
+  s as dotAnalyticsIdentityPlugin
 };

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

@@ -1,24 +1,9 @@
+import { DotCMSEventUtmData } from '../../shared/models';
 /**
- * Updates activity timestamp
+ * Compares UTM parameters to detect campaign changes.
+ * Only checks significant parameters: source, medium, and campaign.
+ * @internal This function is for internal use only.
+ * @param currentUTM - Current UTM parameters in DotCMS format
+ * @returns True if UTM parameters have changed, false otherwise
  */
-export declare const updateActivityTime: () => void;
-/**
- * Checks if user has been inactive
- */
-export declare const isUserInactive: () => boolean;
-/**
- * Checks if a new day has started since session creation
- */
-export declare const hasPassedMidnight: (sessionStartTime: number) => boolean;
-/**
- * Gets the last activity time
- */
-export declare const getLastActivityTime: () => number;
-/**
- * Extracts UTM parameters from current location
- */
-export declare const extractUTMParameters: () => Record<string, string>;
-/**
- * Compares UTM parameters to detect campaign changes
- */
-export declare const hasUTMChanged: (currentUTM: Record<string, string>) => boolean;
+export declare const hasUTMChanged: (currentUTM: DotCMSEventUtmData) => boolean;

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,200 @@
+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, findContentlets as b, extractContentletIdentifier as c, createContentletObserver as f, extractContentletData as v } from "../../shared/utils/dot-analytics.utils.js";
+class C {
+  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(), this.findAndObserveContentletElements(), 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 = f(() => {
+      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 = v(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 {
+  C 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';