@dotcms/analytics 1.2.0-next.4 → 1.2.0-next.6

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/shared/constants/dot-content-analytics.constants.d.ts

@@ -7,6 +7,7 @@ export declare const ANALYTICS_ENDPOINT = "/api/v1/analytics/content/event";
  */
 export declare const DotCMSPredefinedEventType: {
     readonly PAGEVIEW: "pageview";
+    readonly CONTENT_IMPRESSION: "content_impression";
 };
 /**
  * Type for structured events
@@ -68,3 +69,48 @@ 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";
+/**
+ * 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-content-analytics.constants.js

@@ -1,17 +1,18 @@
-const E = "/api/v1/analytics/content/event", e = {
-  PAGEVIEW: "pageview"
-}, n = [
+const s = "/api/v1/analytics/content/event", I = {
+  PAGEVIEW: "pageview",
+  CONTENT_IMPRESSION: "content_impression"
+}, e = [
   "utm_source",
   "utm_medium",
   "utm_campaign",
   "utm_term",
   "utm_content"
-], c = 30, s = "dot_analytics_session_id", T = "dot_analytics_user_id", t = 15, _ = 5e3, o = ["click"], S = {
-  eventBatchSize: t,
+], o = 30, c = "dot_analytics_session_id", N = "dot_analytics_user_id", E = 15, _ = 5e3, O = ["click"], i = {
+  eventBatchSize: E,
   // Max events per batch - auto-sends when reached
   flushInterval: _
   // Time between flushes - sends whatever is queued
-}, I = [
+}, A = [
   "title",
   "url",
   "path",
@@ -20,15 +21,28 @@ const E = "/api/v1/analytics/content/event", e = {
   "width",
   "height",
   "referrer"
-];
+], t = 0.5, S = 750, T = 100, n = 100, U = 250, L = {
+  visibilityThreshold: t,
+  dwellMs: S,
+  maxNodes: T,
+  throttleMs: n
+}, D = "content_impression", M = "dotcms-analytics-contentlet";
 export {
-  o as ACTIVITY_EVENTS,
-  E as ANALYTICS_ENDPOINT,
-  I as ANALYTICS_JS_DEFAULT_PROPERTIES,
-  S as DEFAULT_QUEUE_CONFIG,
-  c as DEFAULT_SESSION_TIMEOUT_MINUTES,
-  e as DotCMSPredefinedEventType,
-  n as EXPECTED_UTM_KEYS,
-  s as SESSION_STORAGE_KEY,
-  T as USER_ID_KEY
+  O as ACTIVITY_EVENTS,
+  M as ANALYTICS_CONTENTLET_CLASS,
+  s as ANALYTICS_ENDPOINT,
+  A as ANALYTICS_JS_DEFAULT_PROPERTIES,
+  L as DEFAULT_IMPRESSION_CONFIG,
+  S as DEFAULT_IMPRESSION_DWELL_MS,
+  T as DEFAULT_IMPRESSION_MAX_NODES,
+  U as DEFAULT_IMPRESSION_MUTATION_OBSERVER_DEBOUNCE_MS,
+  n as DEFAULT_IMPRESSION_THROTTLE_MS,
+  t as DEFAULT_IMPRESSION_VISIBILITY_THRESHOLD,
+  i as DEFAULT_QUEUE_CONFIG,
+  o as DEFAULT_SESSION_TIMEOUT_MINUTES,
+  I as DotCMSPredefinedEventType,
+  e as EXPECTED_UTM_KEYS,
+  D as IMPRESSION_EVENT_TYPE,
+  c as SESSION_STORAGE_KEY,
+  N as USER_ID_KEY
 };

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

@@ -1,4 +1,4 @@
-import { DotCMSAnalyticsConfig, DotCMSEvent, DotCMSRequestBody } from './models';
+import { DotCMSAnalyticsConfig, DotCMSAnalyticsRequestBody } from './models';
 /**
  * Send analytics events to the server using fetch API
  * @param payload - The event payload data
@@ -6,4 +6,4 @@ import { DotCMSAnalyticsConfig, DotCMSEvent, DotCMSRequestBody } from './models'
  * @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: DotCMSRequestBody<DotCMSEvent>, config: DotCMSAnalyticsConfig, keepalive?: boolean) => Promise<void>;
+export declare const sendAnalyticsEvent: (payload: DotCMSAnalyticsRequestBody, config: DotCMSAnalyticsConfig, keepalive?: boolean) => Promise<void>;

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

@@ -0,0 +1,62 @@
+import { DotCMSAnalyticsConfig, DotCMSContentImpressionPayload } from './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 debug;
+    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/shared/dot-content-analytics.impression-tracker.js

@@ -0,0 +1,218 @@
+import { getUVEState as d } from "../../../uve/src/lib/core/core.utils.js";
+import "../../../uve/src/internal/constants.js";
+import { DEFAULT_IMPRESSION_CONFIG as l, ANALYTICS_CONTENTLET_CLASS as a, IMPRESSION_EVENT_TYPE as h, DEFAULT_IMPRESSION_MUTATION_OBSERVER_DEBOUNCE_MS as u } from "./constants/dot-content-analytics.constants.js";
+import { extractContentletIdentifier as c, createDebounce as m, extractContentletData as p, getViewportMetrics as b, isElementMeetingVisibilityThreshold as f } from "../plugin/impression/dot-analytics.impression.utils.js";
+class I {
+  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.debug = e.debug ?? !1, 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.debug && console.error("DotCMS Analytics: 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 (!(typeof window > "u" || typeof document > "u")) {
+      if (d()) {
+        this.debug && console.warn("DotCMS Analytics: Impression tracking disabled in editor mode");
+        return;
+      }
+      this.initializeIntersectionObserver(), this.findAndObserveContentletElements(), this.initializeDynamicContentDetector(), this.initializePageVisibilityHandler(), this.initializePageNavigationHandler(), this.debug && console.warn(
+        "DotCMS Analytics: 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 = document.querySelectorAll(
+      `.${a}`
+    );
+    if (e.length === 0) {
+      this.debug && console.warn("DotCMS Analytics: 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.debug && console.warn(
+            `DotCMS Analytics: Skipping element ${r} (${o})`
+          );
+          continue;
+        }
+        this.elementImpressionStates.has(r) || (this.observer.observe(n), this.elementImpressionStates.set(r, {
+          timer: null,
+          visibleSince: null,
+          tracked: this.hasBeenTrackedInSession(r),
+          element: n
+        }), t++, this.debug && (n.dataset.dotAnalyticsObserved = "true", n.style.outline = "2px solid red", n.style.outlineOffset = "-2px", n.style.transition = "outline-color 0.5s ease-in-out"));
+      }
+    }
+    this.debug && (console.warn(`DotCMS Analytics: Observing ${t} contentlets`), e.length > i && console.warn(
+      `DotCMS Analytics: ${e.length - i} contentlets not tracked (maxNodes limit: ${this.impressionConfig.maxNodes})`
+    ));
+  }
+  /** Watches for new contentlets added to DOM (debounced for performance) */
+  initializeDynamicContentDetector() {
+    if (typeof window > "u" || typeof document > "u")
+      return;
+    const e = m(() => {
+      this.findAndObserveContentletElements();
+    }, u);
+    this.mutationObserver = new MutationObserver(() => {
+      e();
+    }), this.mutationObserver.observe(document.body, {
+      childList: !0,
+      subtree: !0
+    }), this.debug && console.warn(
+      "DotCMS Analytics: 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.debug && console.warn("DotCMS Analytics: 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.debug && console.warn(
+        `DotCMS Analytics: 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();
+    }, setInterval(e, 1e3);
+  }
+  /** 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.debug && console.warn(
+        `DotCMS Analytics: Dwell timer expired for ${e} but element no longer visible, skipping impression`
+      ), t.timer = null, t.visibleSince = null);
+    }, this.impressionConfig.dwellMs), this.debug && console.warn(
+      `DotCMS Analytics: 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.debug && console.warn(`DotCMS Analytics: 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 = p(i), r = b(i), o = {
+      content: {
+        identifier: n.identifier,
+        inode: n.inode,
+        title: n.title,
+        content_type: n.contentType
+      },
+      position: {
+        viewport_offset_pct: r.offsetPercentage,
+        dom_index: Array.from(
+          document.querySelectorAll(`.${a}`)
+        ).indexOf(i)
+      }
+    };
+    this.notifySubscribers(h, o), this.markImpressionAsTracked(e), t.timer = null, t.visibleSince = null, t.tracked = !0, this.observer && this.observer.unobserve(i), this.debug && (i.style.outline = "2px solid green", i.style.outlineOffset = "-2px", console.warn(
+      `DotCMS Analytics: 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 : f(
+      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.debug && console.warn("DotCMS Analytics: Impression tracking cleaned up");
+  }
+}
+export {
+  I as DotCMSImpressionTracker
+};

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

@@ -1,6 +1,26 @@
 import { PageData } from 'analytics';
+import { DotCMSPredefinedEventType } from './constants';
 import { AnalyticsBasePayloadWithContext, DotCMSAnalyticsConfig, DotCMSAnalyticsEventContext, DotCMSBrowserData, DotCMSEventDeviceData, DotCMSEventUtmData, EnrichedAnalyticsPayload } from './models';
 export { cleanupActivityTracking, getLastActivity, getSessionInfo, initializeActivityTracking, isUserInactive, updateSessionActivity } from './dot-content-analytics.activity-tracker';
+/**
+ * Type guard to check if an event is a predefined event type.
+ * Enables TypeScript type narrowing for better type safety.
+ *
+ * @param event - Event name to check
+ * @returns True if event is a predefined type, false for custom events
+ *
+ * @example
+ * ```typescript
+ * if (isPredefinedEventType(eventName)) {
+ *   // TypeScript knows eventName is DotCMSPredefinedEventType here
+ *   console.log('Predefined event:', eventName);
+ * } else {
+ *   // TypeScript knows eventName is string (custom) here
+ *   console.log('Custom event:', eventName);
+ * }
+ * ```
+ */
+export declare function isPredefinedEventType(event: string): event is DotCMSPredefinedEventType;
 /**
  * Validates required configuration fields for Analytics initialization.
  *

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;
+    };
+}

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

@@ -1,4 +1,4 @@
-import { DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
+import { DotCMSContentImpressionPageData, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
 import { DotCMSCustomEventType, DotCMSEventType, DotCMSPredefinedEventType } from '../constants/dot-content-analytics.constants';
 /**
  * JSON value type for analytics custom data.
@@ -50,15 +50,53 @@ export type DotCMSCustomEventData = {
     /** Custom data associated with the event (any valid JSON) */
     custom: JsonObject;
 };
+/**
+ * Partial content impression data sent by producer plugins.
+ * Contains only impression-specific data (content and position).
+ * The enricher plugin will add page data automatically.
+ */
+export type DotCMSContentImpressionPayload = {
+    /** Content information */
+    content: {
+        /** Content identifier */
+        identifier: string;
+        /** Content inode */
+        inode: string;
+        /** Content title */
+        title: string;
+        /** Content type name */
+        content_type: string;
+    };
+    /** Position information in the viewport and DOM */
+    position: {
+        /** Viewport offset percentage from top */
+        viewport_offset_pct: number;
+        /** DOM index position */
+        dom_index: number;
+    };
+};
+/**
+ * Complete data structure for content impression events after enrichment.
+ * Includes minimal page data (title and url) added by the enricher plugin.
+ */
+export type DotCMSContentImpressionEventData = DotCMSContentImpressionPayload & {
+    /** Minimal page data where the impression occurred (added by enricher) */
+    page: DotCMSContentImpressionPageData;
+};
 /**
  * Pageview event structure.
  */
 export type DotCMSPageViewEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.PAGEVIEW, DotCMSPageViewEventData>;
+/**
+ * Content impression event structure.
+ */
+export type DotCMSContentImpressionEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.CONTENT_IMPRESSION, DotCMSContentImpressionEventData>;
 /**
  * Custom event structure.
  */
 export type DotCMSCustomEvent = DotCMSEventBase<DotCMSCustomEventType, DotCMSCustomEventData>;
 /**
  * Union type for all possible analytics events.
+ * Used primarily for type documentation and validation.
  */
-export type DotCMSEvent = DotCMSPageViewEvent | DotCMSCustomEvent;
+export type DotCMSEvent = DotCMSPageViewEvent | DotCMSContentImpressionEvent | DotCMSCustomEvent;