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

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

@@ -1,5 +1,5 @@
-import { DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
-import { DotCMSCustomEventType, DotCMSEventType, DotCMSPredefinedEventType } from '../constants/dot-content-analytics.constants';
+import { DotCMSContentImpressionPageData, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
+import { DotCMSCustomEventType, DotCMSEventType, DotCMSPredefinedEventType } from '../constants/dot-analytics.constants';
 /**
  * JSON value type for analytics custom data.
  * Represents any valid JSON value that can be serialized and sent to the analytics server.
@@ -50,15 +50,86 @@ 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;
+    };
+};
+/**
+ * Partial content click data sent by producer plugins.
+ * Extends impression payload with element metadata.
+ */
+export type DotCMSContentClickPayload = DotCMSContentImpressionPayload & {
+    /** Clicked element information */
+    element: {
+        /** Text content of the element */
+        text: string;
+        /** Type of element (anchor, button, etc.) */
+        type: string;
+        /** Element ID (required by backend, empty string if not present) */
+        id: string;
+        /** Element classes (required by backend, empty string if not present) */
+        class: string;
+        /** Link destination as written in HTML (relative path, only for <a> elements, empty string for buttons) */
+        href: string;
+        /** Additional element attributes in key:value format (e.g., ['data-category:val', 'data-campaign:val2']) */
+        attributes: string[];
+    };
+};
+/**
+ * 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;
+};
+/**
+ * Complete data structure for content click events after enrichment.
+ * Includes minimal page data (title and url) added by the enricher plugin.
+ */
+export type DotCMSContentClickEventData = DotCMSContentClickPayload & {
+    /** Minimal page data where the click 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>;
+/**
+ * Content click event structure.
+ */
+export type DotCMSContentClickEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.CONTENT_CLICK, DotCMSContentClickEventData>;
 /**
  * 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 | DotCMSContentClickEvent | DotCMSCustomEvent;

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

@@ -1,7 +1,7 @@
-import { DotCMSAnalyticsEventContext, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
-import { JsonObject } from './event.model';
+import { DotCMSAnalyticsEventContext, DotCMSContentImpressionPageData, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
+import { DotCMSContentImpressionPayload, JsonObject } from './event.model';
 import { DotCMSAnalyticsRequestBody } from './request.model';
-import { DotCMSCustomEventType } from '../constants';
+import { LogLevel } from '../dot-analytics.logger';
 /**
  * Configuration for event queue management.
  * Controls how events are batched before sending to the server.
@@ -12,6 +12,37 @@ export interface QueueConfig {
     /** Time in milliseconds between flushes - sends pending events (default: 5000) */
     flushInterval?: number;
 }
+/**
+ * Configuration for content impression tracking.
+ * Controls how content visibility is detected and tracked.
+ */
+export interface ImpressionConfig {
+    /** Minimum percentage of element visible (0.0 to 1.0) - default: 0.5 */
+    visibilityThreshold?: number;
+    /** Minimum time in milliseconds element must be visible - default: 750 */
+    dwellMs?: number;
+    /** Maximum number of elements to track (performance limit) - default: 1000 */
+    maxNodes?: number;
+    /** Throttle time in milliseconds for intersection callbacks - default: 100 */
+    throttleMs?: number;
+}
+/**
+ * Interface for contentlet data extracted from DOM elements
+ */
+export interface ContentletData {
+    identifier: string;
+    inode: string;
+    contentType: string;
+    title: string;
+    baseType: string;
+}
+/**
+ * Interface for viewport metrics
+ */
+export interface ViewportMetrics {
+    offsetPercentage: number;
+    visibilityRatio: number;
+}
 /**
  * Main interface for the DotCMS Analytics SDK.
  * Provides the core methods for tracking page views and custom events.
@@ -42,6 +73,16 @@ export interface DotCMSAnalyticsConfig {
      * Enable debug mode to get additional logging information.
      */
     debug: boolean;
+    /**
+     * Set the minimum log level for console output.
+     * - 'debug': Show all logs including detailed debugging information
+     * - 'info': Show informational messages, warnings, and errors
+     * - 'warn': Show only warnings and errors
+     * - 'error': Show only errors
+     *
+     * If not specified, falls back to debug flag (debug=true → 'debug', debug=false → 'warn')
+     */
+    logLevel?: LogLevel;
     /**
      * Automatically track page views when set to true.
      */
@@ -57,15 +98,28 @@ export interface DotCMSAnalyticsConfig {
      * - `QueueConfig`: Enable queuing with custom settings
      */
     queue?: QueueConfig | boolean;
+    /**
+     * Content impression tracking configuration (default: undefined - disabled):
+     * - `undefined` or `false`: Impression tracking disabled
+     * - `true`: Enable with default settings (threshold: 0.5, dwell: 750ms, maxNodes: 1000)
+     * - `ImpressionConfig`: Enable with custom settings
+     */
+    impressions?: ImpressionConfig | boolean;
+    /**
+     * Content click tracking configuration (default: undefined - disabled):
+     * - `undefined` or `false`: Click tracking disabled
+     * - `true`: Enable click tracking
+     */
+    clicks?: boolean;
 }
 /**
  * Track event payload with context.
- * This is the payload for custom track events after the identity plugin adds context.
+ * This is the payload for track events after the identity plugin adds context.
  * Used in the track:dot-analytics enricher plugin.
  */
 export interface AnalyticsTrackPayloadWithContext extends AnalyticsBasePayload {
-    /** The custom event name (any string except 'pageview') */
-    event: DotCMSCustomEventType;
+    /** The event name (can be predefined or custom) */
+    event: string;
     /** Analytics context added by identity plugin */
     context: DotCMSAnalyticsEventContext;
 }
@@ -84,29 +138,16 @@ type AnalyticsBasePayloadType = 'page' | 'track';
  * Analytics.js hook parameter types for DotCMS.
  * Represents the payload structure used by Analytics.js lifecycle hooks
  * for intercepting and modifying analytics events.
+ *
+ * Properties are flexible (Record<string, unknown>) to support both:
+ * - Page events: with page-specific fields (title, url, path, etc.)
+ * - Track events: with any custom event data structure
  */
 export interface AnalyticsBasePayload {
     /** The type of analytics event */
     type: AnalyticsBasePayloadType;
-    /** Properties associated with the event */
-    properties: {
-        /** Page title */
-        title: string;
-        /** Page URL */
-        url: string;
-        /** Page path */
-        path: string;
-        /** URL hash fragment */
-        hash: string;
-        /** URL search parameters */
-        search: string;
-        /** Viewport width */
-        width: number;
-        /** Viewport height */
-        height: number;
-        /** Referrer URL */
-        referrer?: string;
-    };
+    /** Properties associated with the event (flexible structure) */
+    properties: Record<string, unknown>;
     /** Configuration options for the event */
     options: Record<string, unknown>;
     /** User identifier */
@@ -146,6 +187,17 @@ export type EnrichedAnalyticsPayload = AnalyticsBasePayloadWithContext & {
     /** Local timestamp when the event occurred */
     local_time: string;
 };
+/**
+ * Enriched track event payload with fields added to root based on event type.
+ * Used by the enricher plugin for track events.
+ */
+export interface EnrichedTrackPayload extends AnalyticsTrackPayloadWithContext {
+    local_time: string;
+    page?: DotCMSContentImpressionPageData | DotCMSEventPageData;
+    content?: DotCMSContentImpressionPayload['content'];
+    position?: DotCMSContentImpressionPayload['position'];
+    utm?: DotCMSEventUtmData;
+}
 /**
  * Analytics.js instance structure for DotCMS.
  * Represents the internal structure of an Analytics.js instance,

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

@@ -1,24 +1,32 @@
 import { DotCMSAnalyticsEventContext } from './data.model';
-import { DotCMSCustomEvent, DotCMSEvent, DotCMSPageViewEvent } from './event.model';
+import { DotCMSEvent } from './event.model';
 /**
  * Analytics request body for DotCMS Analytics.
  * Generic structure sent to the DotCMS analytics server.
+ *
+ * This structure contains properly typed events that match the DotCMS event specifications.
+ * Events can be pageviews, content impressions, or custom events, each with their own data structure.
  */
-export interface DotCMSRequestBody<T extends DotCMSEvent> {
+export interface DotCMSRequestBody {
     /** Context information shared across all events */
     context: DotCMSAnalyticsEventContext;
     /** Array of analytics events to be tracked */
-    events: T[];
+    events: DotCMSEvent[];
 }
 /**
- * Specific request body type for PageView events
+ * Main type for analytics request bodies.
+ * Flexible enough to accept any event type (pageview, content_impression, custom, etc.)
  */
-export type DotCMSPageViewRequestBody = DotCMSRequestBody<DotCMSPageViewEvent>;
+export type DotCMSAnalyticsRequestBody = DotCMSRequestBody;
 /**
- * Specific request body type for Custom events
+ * Specific request body type for PageView events (for type documentation)
  */
-export type DotCMSCustomEventRequestBody = DotCMSRequestBody<DotCMSCustomEvent>;
+export type DotCMSPageViewRequestBody = DotCMSRequestBody;
 /**
- * Union type for all possible request bodies
+ * Specific request body type for ContentImpression events (for type documentation)
  */
-export type DotCMSAnalyticsRequestBody = DotCMSPageViewRequestBody | DotCMSCustomEventRequestBody;
+export type DotCMSContentImpressionRequestBody = DotCMSRequestBody;
+/**
+ * Specific request body type for Custom events (for type documentation)
+ */
+export type DotCMSCustomEventRequestBody = DotCMSRequestBody;

package/lib/core/shared/queue/dot-analytics.queue.utils.js

@@ -1,40 +1,51 @@
-import p from "@analytics/queue-utils";
-import { DEFAULT_QUEUE_CONFIG as c } from "../constants/dot-content-analytics.constants.js";
-import { sendAnalyticsEvent as y } from "../dot-content-analytics.http.js";
-const z = (n) => {
-  let e = null, i = null, o = "fetch";
-  const l = {
-    ...c,
-    ...typeof n.queue == "object" ? n.queue : {}
-  }, f = (t) => {
-    if (!i) return;
-    n.debug && console.log(`DotCMS Analytics Queue: Sending batch of ${t.length} event(s)`, {
+import m from "@analytics/queue-utils";
+import v from "@analytics/router-utils";
+import { DEFAULT_QUEUE_CONFIG as y } from "../constants/dot-analytics.constants.js";
+import { sendAnalyticsEvent as b } from "../http/dot-analytics.http.js";
+import { createPluginLogger as w } from "../utils/dot-analytics.utils.js";
+const L = (o) => {
+  const i = w("Queue", o);
+  let e = null, n = null, u = !1, d = !1, f = typeof window < "u" ? window.location.pathname : "";
+  const a = {
+    ...y,
+    ...typeof o.queue == "object" ? o.queue : {}
+  }, g = (t, s) => {
+    if (!n) return;
+    i.debug(`Sending batch of ${t.length} event(s)`, {
       events: t,
-      transport: o
-    }), y({ context: i, events: t }, n, o);
-  }, u = () => {
-    !e || e.size() === 0 || !i || (n.debug && console.warn(
-      `DotCMS Analytics: Flushing ${e.size()} events (page hidden/unload)`
-    ), o = "beacon", e.flush(!0));
-  }, d = () => {
-    document.visibilityState === "hidden" && u();
+      keepalive: u
+    }), b({ context: n, events: t }, o, u);
+  }, l = () => {
+    !e || e.size() === 0 || !n || (i.info(`Flushing ${e.size()} events (page hidden/unload)`), u = !0, e.flush(!0));
+  }, c = () => {
+    if (i.debug("handleVisibilityChange", document.visibilityState), document.visibilityState === "hidden") {
+      if (d) {
+        i.debug("Skipping flush (SPA navigation detected)");
+        return;
+      }
+      l();
+    } else document.visibilityState === "visible" && (d = !1);
   };
   return {
     /**
      * Initialize the queue with smart batching
      */
     initialize: () => {
-      e = p(
-        (t) => {
-          f(t);
+      e = m(
+        (t, s) => {
+          g(t);
         },
         {
-          max: l.eventBatchSize,
-          interval: l.flushInterval,
+          max: a.eventBatchSize,
+          interval: a.flushInterval,
           throttle: !1
           // Always false - enables both batch size and interval triggers
         }
-      ), typeof window < "u" && typeof document < "u" && (document.addEventListener("visibilitychange", d), window.addEventListener("pagehide", u));
+      ), typeof window < "u" && typeof document < "u" && (document.addEventListener("visibilitychange", c), window.addEventListener("pagehide", l), v((t) => {
+        d = !0, f = t, i.debug(`SPA navigation detected (${f})`), setTimeout(() => {
+          d = !1;
+        }, 100);
+      }));
     },
     /**
      * Add event to queue
@@ -43,16 +54,12 @@ const z = (n) => {
      * - Sends pending events every flushInterval
      */
     enqueue: (t, s) => {
-      if (i = s, !!e) {
-        if (n.debug) {
-          const a = e.size() + 1, r = l.eventBatchSize ?? c.eventBatchSize, h = a >= r;
-          console.log(
-            `DotCMS Analytics Queue: Event added. Queue size: ${a}/${r}${h ? " (full, sending...)" : ""}`,
-            { eventType: t.event_type, event: t }
-          );
-        }
-        e.push(t);
-      }
+      if (n = s, !e) return;
+      const r = e.size() + 1, p = a.eventBatchSize, h = r >= p;
+      i.debug(
+        `Event added. Queue size: ${r}/${p}${h ? " (full, sending...)" : ""}`,
+        { eventType: t.event_type, event: t }
+      ), e.push(t);
     },
     /**
      * Get queue size for debugging
@@ -64,10 +71,10 @@ const z = (n) => {
      * Flushes remaining events and cleans up listeners
      */
     cleanup: () => {
-      u(), typeof window < "u" && typeof document < "u" && (document.removeEventListener("visibilitychange", d), window.removeEventListener("pagehide", u)), e = null, i = null, o = "fetch";
+      l(), typeof window < "u" && typeof document < "u" && (document.removeEventListener("visibilitychange", c), window.removeEventListener("pagehide", l)), e = null, n = null, u = !1;
     }
   };
 };
 export {
-  z as createAnalyticsQueue
+  L as createAnalyticsQueue
 };

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

@@ -1,6 +1,27 @@
-import { PageData } from 'analytics';
-import { AnalyticsBasePayloadWithContext, DotCMSAnalyticsConfig, DotCMSAnalyticsEventContext, DotCMSBrowserData, DotCMSEventDeviceData, DotCMSEventUtmData, EnrichedAnalyticsPayload } from './models';
-export { cleanupActivityTracking, getLastActivity, getSessionInfo, initializeActivityTracking, isUserInactive, updateSessionActivity } from './dot-content-analytics.activity-tracker';
+import { AnalyticsPlugin, PageData } from 'analytics';
+import { DotCMSPredefinedEventType } from '../constants';
+import { DotLogger, LogLevel } from '../dot-analytics.logger';
+import { AnalyticsBasePayloadWithContext, ContentletData, DotCMSAnalyticsConfig, DotCMSAnalyticsEventContext, DotCMSBrowserData, DotCMSEventDeviceData, DotCMSEventUtmData, EnrichedAnalyticsPayload } from '../models';
+export { cleanupActivityTracking, initializeActivityTracking, updateSessionActivity } from '../../plugin/identity/dot-analytics.identity.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.
  *
@@ -170,3 +191,70 @@ export declare const enrichPagePayload: (payload: {
         properties: Record<string, unknown>;
     };
 };
+/**
+ * Creates a throttled version of a callback function
+ * Ensures the callback is executed at most once every `limitMs` milliseconds
+ * @param callback - The function to throttle
+ * @param limitMs - The time limit in milliseconds
+ * @returns A throttled function
+ */
+export declare function createThrottle<T extends (...args: unknown[]) => void>(callback: T, limitMs: number): (...args: Parameters<T>) => void;
+/**
+ * Extracts the contentlet identifier from a DOM element
+ * @param element - The HTML element containing data attributes
+ * @returns The contentlet identifier or null if not found
+ */
+export declare function extractContentletIdentifier(element: HTMLElement): string | null;
+/**
+ * Extracts all contentlet data from a DOM element's data attributes
+ * @param element - The HTML element containing data attributes
+ * @returns Complete contentlet data object
+ */
+export declare function extractContentletData(element: HTMLElement): ContentletData;
+/**
+ * Initial scan delay for DOM readiness
+ * Allows React/Next.js to finish rendering before scanning for contentlets
+ */
+export declare const INITIAL_SCAN_DELAY_MS = 100;
+/**
+ * Checks if code is running in a browser environment
+ * @returns true if window and document are available
+ */
+export declare const isBrowser: () => boolean;
+/**
+ * Finds all contentlet elements in the DOM
+ * @returns Array of contentlet HTMLElements
+ */
+export declare const findContentlets: () => HTMLElement[];
+/**
+ * Creates a MutationObserver that watches for contentlet changes in the DOM
+ * @param callback - Function to call when mutations are detected
+ * @param debounceMs - Debounce time in milliseconds (default: 250ms)
+ * @returns Configured and active MutationObserver
+ */
+export declare const createContentletObserver: (callback: () => void, debounceMs?: number) => MutationObserver;
+/**
+ * Sets up cleanup handlers for page unload events
+ * Registers cleanup function to both 'beforeunload' and 'pagehide' for maximum compatibility
+ * @param cleanup - Function to call on page unload
+ */
+export declare const setupPluginCleanup: (cleanup: () => void) => void;
+/**
+ * Creates a logger with plugin-specific prefix and configurable log level
+ * @param pluginName - Name of the plugin (e.g., 'Click', 'Impression')
+ * @param config - Analytics configuration with debug flag and optional logLevel
+ * @returns DotLogger instance with configured log level
+ */
+export declare const createPluginLogger: (pluginName: string, config: {
+    debug: boolean;
+    logLevel?: LogLevel;
+}) => DotLogger;
+/**
+ * Gets enhanced tracking plugins based on configuration
+ * Returns content impression and click tracking plugins if enabled
+ * @param config - Analytics configuration
+ * @param impressionPlugin - Impression tracking plugin factory
+ * @param clickPlugin - Click tracking plugin factory
+ * @returns Array of enabled tracking plugins
+ */
+export declare const getEnhancedTrackingPlugins: (config: DotCMSAnalyticsConfig, impressionPlugin: (config: DotCMSAnalyticsConfig) => AnalyticsPlugin, clickPlugin: (config: DotCMSAnalyticsConfig) => AnalyticsPlugin) => AnalyticsPlugin[];