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

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

@@ -1,7 +1,6 @@
-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';
 /**
  * Configuration for event queue management.
  * Controls how events are batched before sending to the server.
@@ -12,6 +11,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.
@@ -57,15 +87,22 @@ export interface DotCMSAnalyticsConfig {
      * - `QueueConfig`: Enable queuing with custom settings
      */
     queue?: QueueConfig | boolean;
+    /**
+     * Content impression tracking configuration:
+     * - `undefined` or `false` (default): Impression tracking disabled
+     * - `true`: Enable with default settings (threshold: 0.5, dwell: 750ms, maxNodes: 1000)
+     * - `ImpressionConfig`: Enable with custom settings
+     */
+    impressions?: ImpressionConfig | 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 +121,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 +170,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/analytics",
-  "version": "1.2.0-next.4",
+  "version": "1.2.0-next.6",
   "description": "Official JavaScript library for Content Analytics with DotCMS.",
   "repository": {
     "type": "git",