@dotcms/analytics 1.2.0 → 1.2.1-next.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +314 -9
  2. package/lib/core/dot-analytics.content.js +84 -0
  3. package/lib/core/plugin/click/dot-analytics.click-tracker.d.ts +108 -0
  4. package/lib/core/plugin/click/dot-analytics.click-tracker.js +144 -0
  5. package/lib/core/plugin/click/dot-analytics.click.plugin.d.ts +36 -0
  6. package/lib/core/plugin/click/dot-analytics.click.plugin.js +27 -0
  7. package/lib/core/plugin/click/dot-analytics.click.utils.d.ts +12 -0
  8. package/lib/core/plugin/click/dot-analytics.click.utils.js +55 -0
  9. package/lib/core/plugin/enricher/dot-analytics.enricher.plugin.d.ts +14 -10
  10. package/lib/core/plugin/enricher/dot-analytics.enricher.plugin.js +26 -38
  11. package/lib/core/{shared/dot-content-analytics.activity-tracker.d.ts → plugin/identity/dot-analytics.identity.activity-tracker.d.ts} +2 -17
  12. package/lib/core/{shared/dot-content-analytics.activity-tracker.js → plugin/identity/dot-analytics.identity.activity-tracker.js} +17 -38
  13. package/lib/core/plugin/identity/dot-analytics.identity.plugin.d.ts +2 -20
  14. package/lib/core/plugin/identity/dot-analytics.identity.plugin.js +7 -7
  15. package/lib/core/plugin/identity/dot-analytics.identity.utils.d.ts +0 -16
  16. package/lib/core/plugin/impression/dot-analytics.impression-tracker.d.ts +62 -0
  17. package/lib/core/plugin/impression/dot-analytics.impression-tracker.js +202 -0
  18. package/lib/core/plugin/impression/dot-analytics.impression.plugin.d.ts +40 -0
  19. package/lib/core/plugin/impression/dot-analytics.impression.plugin.js +27 -0
  20. package/lib/core/plugin/impression/dot-analytics.impression.utils.d.ts +26 -0
  21. package/lib/core/plugin/impression/dot-analytics.impression.utils.js +27 -0
  22. package/lib/core/plugin/impression/index.d.ts +2 -0
  23. package/lib/core/plugin/main/dot-analytics.plugin.d.ts +46 -0
  24. package/lib/core/plugin/main/dot-analytics.plugin.js +129 -0
  25. package/lib/core/shared/constants/{dot-content-analytics.constants.d.ts → dot-analytics.constants.d.ts} +62 -0
  26. package/lib/core/shared/constants/dot-analytics.constants.js +53 -0
  27. package/lib/core/shared/constants/index.d.ts +1 -1
  28. package/lib/core/shared/dot-analytics.logger.d.ts +85 -0
  29. package/lib/core/shared/dot-analytics.logger.js +90 -0
  30. package/lib/core/shared/http/dot-analytics.http.d.ts +9 -0
  31. package/lib/core/shared/http/dot-analytics.http.js +34 -0
  32. package/lib/core/shared/models/data.model.d.ts +39 -1
  33. package/lib/core/shared/models/event.model.d.ts +108 -3
  34. package/lib/core/shared/models/library.model.d.ts +89 -28
  35. package/lib/core/shared/models/request.model.d.ts +17 -9
  36. package/lib/core/shared/queue/dot-analytics.queue.utils.js +47 -40
  37. package/lib/core/shared/{dot-content-analytics.utils.d.ts → utils/dot-analytics.utils.d.ts} +91 -3
  38. package/lib/core/shared/utils/dot-analytics.utils.js +200 -0
  39. package/lib/react/hook/useContentAnalytics.js +17 -11
  40. package/lib/react/hook/useRouterTracker.js +12 -12
  41. package/lib/react/internal/utils.js +1 -1
  42. package/package.json +7 -6
  43. package/uve/src/internal/events.js +30 -31
  44. package/uve/src/lib/dom/dom.utils.js +46 -52
  45. package/lib/core/dot-content-analytics.js +0 -46
  46. package/lib/core/plugin/dot-analytics.plugin.d.ts +0 -33
  47. package/lib/core/plugin/dot-analytics.plugin.js +0 -42
  48. package/lib/core/shared/constants/dot-content-analytics.constants.js +0 -34
  49. package/lib/core/shared/dot-content-analytics.http.d.ts +0 -17
  50. package/lib/core/shared/dot-content-analytics.http.js +0 -41
  51. package/lib/core/shared/dot-content-analytics.utils.js +0 -147
  52. /package/lib/core/{dot-content-analytics.d.ts → dot-analytics.content.d.ts} +0 -0
@@ -0,0 +1,53 @@
1
+ const I = "/api/v1/analytics/content/event", c = {
2
+ PAGEVIEW: "pageview",
3
+ CONTENT_IMPRESSION: "content_impression",
4
+ CONTENT_CLICK: "content_click",
5
+ CONVERSION: "conversion"
6
+ }, s = [
7
+ "utm_source",
8
+ "utm_medium",
9
+ "utm_campaign",
10
+ "utm_term",
11
+ "utm_content"
12
+ ], o = 30, e = "dot_analytics_session_id", N = "dot_analytics_user_id", E = 15, _ = 5e3, L = ["click"], O = {
13
+ eventBatchSize: E,
14
+ // Max events per batch - auto-sends when reached
15
+ flushInterval: _
16
+ // Time between flushes - sends whatever is queued
17
+ }, i = [
18
+ "title",
19
+ "url",
20
+ "path",
21
+ "hash",
22
+ "search",
23
+ "width",
24
+ "height",
25
+ "referrer"
26
+ ], t = 0.5, T = 750, n = 100, S = 100, A = 250, C = {
27
+ visibilityThreshold: t,
28
+ dwellMs: T,
29
+ maxNodes: n,
30
+ throttleMs: S
31
+ }, U = "content_impression", M = "content_click", D = 300, R = "a, button", a = "dotcms-analytics-contentlet";
32
+ export {
33
+ L as ACTIVITY_EVENTS,
34
+ a as ANALYTICS_CONTENTLET_CLASS,
35
+ I as ANALYTICS_ENDPOINT,
36
+ i as ANALYTICS_JS_DEFAULT_PROPERTIES,
37
+ R as CLICKABLE_ELEMENTS_SELECTOR,
38
+ M as CLICK_EVENT_TYPE,
39
+ D as DEFAULT_CLICK_THROTTLE_MS,
40
+ C as DEFAULT_IMPRESSION_CONFIG,
41
+ T as DEFAULT_IMPRESSION_DWELL_MS,
42
+ n as DEFAULT_IMPRESSION_MAX_NODES,
43
+ A as DEFAULT_IMPRESSION_MUTATION_OBSERVER_DEBOUNCE_MS,
44
+ S as DEFAULT_IMPRESSION_THROTTLE_MS,
45
+ t as DEFAULT_IMPRESSION_VISIBILITY_THRESHOLD,
46
+ O as DEFAULT_QUEUE_CONFIG,
47
+ o as DEFAULT_SESSION_TIMEOUT_MINUTES,
48
+ c as DotCMSPredefinedEventType,
49
+ s as EXPECTED_UTM_KEYS,
50
+ U as IMPRESSION_EVENT_TYPE,
51
+ e as SESSION_STORAGE_KEY,
52
+ N as USER_ID_KEY
53
+ };
@@ -1,4 +1,4 @@
1
1
  /**
2
2
  * Central export point for all DotCMS Analytics constants
3
3
  */
4
- export * from './dot-content-analytics.constants';
4
+ export * from './dot-analytics.constants';
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Log level type for the DotLogger
3
+ */
4
+ export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
5
+ /**
6
+ * Log level constants for convenient usage
7
+ */
8
+ export declare const LOG_LEVELS: {
9
+ readonly DEBUG: "debug";
10
+ readonly INFO: "info";
11
+ readonly WARN: "warn";
12
+ readonly ERROR: "error";
13
+ };
14
+ /**
15
+ * Custom logger for DotCMS SDK
16
+ * Provides structured logging with context identification and configurable log level filtering
17
+ *
18
+ * @example
19
+ * ```typescript
20
+ * const logger = new DotLogger('Analytics', 'Impression', 'info');
21
+ * logger.debug('This will not show'); // Below threshold
22
+ * logger.info('Tracker initialized'); // Shows
23
+ * logger.error('Failed to track'); // Shows
24
+ * ```
25
+ */
26
+ export declare class DotLogger {
27
+ private readonly packageName;
28
+ private readonly context;
29
+ private readonly minLevel;
30
+ constructor(packageName: string, context: string, minLevel?: LogLevel);
31
+ /**
32
+ * Creates the formatted prefix for log messages
33
+ * Format: [DotCMS PackageName | Context] [LEVEL]
34
+ */
35
+ private getPrefix;
36
+ /**
37
+ * Checks if a log level should be displayed based on the minimum threshold
38
+ */
39
+ private shouldLog;
40
+ /**
41
+ * Log a DEBUG level message
42
+ * Used for detailed debugging information
43
+ */
44
+ debug(...args: unknown[]): void;
45
+ /**
46
+ * Log an INFO level message
47
+ * Used for general informational messages
48
+ */
49
+ info(...args: unknown[]): void;
50
+ /**
51
+ * Log a WARN level message
52
+ * Used for warning messages that don't prevent operation
53
+ */
54
+ warn(...args: unknown[]): void;
55
+ /**
56
+ * Log an ERROR level message
57
+ * Always logs regardless of threshold for critical errors
58
+ */
59
+ error(...args: unknown[]): void;
60
+ /**
61
+ * Create a console group for organizing related log messages
62
+ * Respects the minimum log level threshold
63
+ */
64
+ group(label: string): void;
65
+ /**
66
+ * End the current console group
67
+ * Respects the minimum log level threshold
68
+ */
69
+ groupEnd(): void;
70
+ /**
71
+ * Start a timer with the given label
72
+ * Useful for performance measurements
73
+ */
74
+ time(label: string): void;
75
+ /**
76
+ * End a timer and log the elapsed time
77
+ * Useful for performance measurements
78
+ */
79
+ timeEnd(label: string): void;
80
+ /**
81
+ * Log a message (alias for info)
82
+ * Provided for backward compatibility
83
+ */
84
+ log(...args: unknown[]): void;
85
+ }
@@ -0,0 +1,90 @@
1
+ const o = {
2
+ debug: 0,
3
+ info: 1,
4
+ warn: 2,
5
+ error: 3
6
+ };
7
+ class r {
8
+ constructor(e, i, t = "warn") {
9
+ this.packageName = e, this.context = i, this.minLevel = t;
10
+ }
11
+ /**
12
+ * Creates the formatted prefix for log messages
13
+ * Format: [DotCMS PackageName | Context] [LEVEL]
14
+ */
15
+ getPrefix(e) {
16
+ return `[DotCMS ${this.packageName} | ${this.context}] [${e.toUpperCase()}]`;
17
+ }
18
+ /**
19
+ * Checks if a log level should be displayed based on the minimum threshold
20
+ */
21
+ shouldLog(e) {
22
+ return o[e] >= o[this.minLevel];
23
+ }
24
+ /**
25
+ * Log a DEBUG level message
26
+ * Used for detailed debugging information
27
+ */
28
+ debug(...e) {
29
+ this.shouldLog("debug") && console.log(this.getPrefix("debug"), ...e);
30
+ }
31
+ /**
32
+ * Log an INFO level message
33
+ * Used for general informational messages
34
+ */
35
+ info(...e) {
36
+ this.shouldLog("info") && console.info(this.getPrefix("info"), ...e);
37
+ }
38
+ /**
39
+ * Log a WARN level message
40
+ * Used for warning messages that don't prevent operation
41
+ */
42
+ warn(...e) {
43
+ this.shouldLog("warn") && console.warn(this.getPrefix("warn"), ...e);
44
+ }
45
+ /**
46
+ * Log an ERROR level message
47
+ * Always logs regardless of threshold for critical errors
48
+ */
49
+ error(...e) {
50
+ console.error(this.getPrefix("error"), ...e);
51
+ }
52
+ /**
53
+ * Create a console group for organizing related log messages
54
+ * Respects the minimum log level threshold
55
+ */
56
+ group(e) {
57
+ this.shouldLog("debug") && console.group(`${this.getPrefix("debug")} ${e}`);
58
+ }
59
+ /**
60
+ * End the current console group
61
+ * Respects the minimum log level threshold
62
+ */
63
+ groupEnd() {
64
+ this.shouldLog("debug") && console.groupEnd();
65
+ }
66
+ /**
67
+ * Start a timer with the given label
68
+ * Useful for performance measurements
69
+ */
70
+ time(e) {
71
+ this.shouldLog("debug") && console.time(`${this.getPrefix("debug")} ${e}`);
72
+ }
73
+ /**
74
+ * End a timer and log the elapsed time
75
+ * Useful for performance measurements
76
+ */
77
+ timeEnd(e) {
78
+ this.shouldLog("debug") && console.timeEnd(`${this.getPrefix("debug")} ${e}`);
79
+ }
80
+ /**
81
+ * Log a message (alias for info)
82
+ * Provided for backward compatibility
83
+ */
84
+ log(...e) {
85
+ this.info(...e);
86
+ }
87
+ }
88
+ export {
89
+ r as DotLogger
90
+ };
@@ -0,0 +1,9 @@
1
+ import { DotCMSAnalyticsConfig, DotCMSAnalyticsRequestBody } from '../models';
2
+ /**
3
+ * Send analytics events to the server using fetch API
4
+ * @param payload - The event payload data
5
+ * @param config - The analytics configuration
6
+ * @param keepalive - Use keepalive mode for page unload scenarios (default: false)
7
+ * @returns A promise that resolves when the request is complete
8
+ */
9
+ export declare const sendAnalyticsEvent: (payload: DotCMSAnalyticsRequestBody, config: DotCMSAnalyticsConfig, keepalive?: boolean) => Promise<void>;
@@ -0,0 +1,34 @@
1
+ import { ANALYTICS_ENDPOINT as f } from "../constants/dot-analytics.constants.js";
2
+ import { createPluginLogger as T } from "../utils/dot-analytics.utils.js";
3
+ const h = async (n, a, i = !1) => {
4
+ const r = T("HTTP", a), c = `${a.server}${f}`, g = JSON.stringify(n);
5
+ r.info(`Sending ${n.events.length} event(s)${i ? " (keepalive)" : ""}`, {
6
+ payload: n
7
+ });
8
+ try {
9
+ const e = {
10
+ method: "POST",
11
+ headers: { "Content-Type": "application/json" },
12
+ body: g
13
+ };
14
+ if (i) {
15
+ e.keepalive = !0, e.credentials = "omit", fetch(c, e);
16
+ return;
17
+ }
18
+ const t = await fetch(c, e);
19
+ if (!t.ok) {
20
+ const p = t.statusText || "Unknown Error", o = `HTTP ${t.status}: ${p}`;
21
+ try {
22
+ const s = await t.json();
23
+ s.message ? r.warn(`${s.message} (${o})`) : r.warn(`${o} - No error message in response`);
24
+ } catch (s) {
25
+ r.warn(`${o} - Failed to parse error response:`, s);
26
+ }
27
+ }
28
+ } catch (e) {
29
+ r.error("Error sending event:", e);
30
+ }
31
+ };
32
+ export {
33
+ h as sendAnalyticsEvent
34
+ };
@@ -89,7 +89,7 @@ export interface DotCMSEventUtmData {
89
89
  id?: string;
90
90
  }
91
91
  /**
92
- * Page data structure for DotCMS analytics.
92
+ * Page data structure for DotCMS analytics (used in pageview events).
93
93
  * Contains comprehensive information about the current page and its context
94
94
  * within the DotCMS environment.
95
95
  */
@@ -101,3 +101,41 @@ export type DotCMSEventPageData = Pick<DotCMSBrowserData, 'url' | 'doc_path' | '
101
101
  /** Persona identifier */
102
102
  persona?: string;
103
103
  };
104
+ /**
105
+ * Minimal page data for content impression events.
106
+ * Contains only essential page information (title and url) to keep payload lightweight.
107
+ */
108
+ export type DotCMSContentImpressionPageData = Pick<DotCMSEventPageData, 'title' | 'url'>;
109
+ /**
110
+ * Data structure for content impression events.
111
+ * Tracks when a contentlet becomes visible in the viewport.
112
+ */
113
+ export interface DotCMSImpressionEventData {
114
+ /** Contentlet identification data extracted from data-dot-analytics-* attributes */
115
+ contentlet: {
116
+ /** Unique identifier of the contentlet */
117
+ identifier: string;
118
+ /** Inode of the contentlet */
119
+ inode: string;
120
+ /** Content type name */
121
+ contentType: string;
122
+ /** Title of the contentlet */
123
+ title: string;
124
+ /** Base type of the contentlet (e.g., CONTENT, WIDGET) */
125
+ baseType: string;
126
+ };
127
+ /** Viewport position and visibility metrics */
128
+ viewport: {
129
+ /** Percentage offset from top of viewport (0-100) */
130
+ offsetPercentage: number;
131
+ /** Percentage of element visible in viewport (0-1) */
132
+ visibilityRatio: number;
133
+ };
134
+ /** Timing information about the impression */
135
+ timing: {
136
+ /** Time in milliseconds the element was continuously visible */
137
+ dwellTime: number;
138
+ /** ISO 8601 timestamp when the impression was fired */
139
+ timestamp: string;
140
+ };
141
+ }
@@ -1,5 +1,5 @@
1
- import { DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
2
- import { DotCMSCustomEventType, DotCMSEventType, DotCMSPredefinedEventType } from '../constants/dot-content-analytics.constants';
1
+ import { DotCMSContentImpressionPageData, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
2
+ import { DotCMSCustomEventType, DotCMSEventType, DotCMSPredefinedEventType } from '../constants/dot-analytics.constants';
3
3
  /**
4
4
  * JSON value type for analytics custom data.
5
5
  * Represents any valid JSON value that can be serialized and sent to the analytics server.
@@ -50,15 +50,120 @@ export type DotCMSCustomEventData = {
50
50
  /** Custom data associated with the event (any valid JSON) */
51
51
  custom: JsonObject;
52
52
  };
53
+ /**
54
+ * Element information for analytics events.
55
+ * Base type for element metadata in click and conversion events.
56
+ */
57
+ export type DotCMSElementData = {
58
+ /** Text content of the element */
59
+ text: string;
60
+ /** Type of element (anchor, button, input, etc.) */
61
+ type: string;
62
+ /** Element ID (required by backend, empty string if not present) */
63
+ id: string;
64
+ /** Element classes (required by backend, empty string if not present) */
65
+ class: string;
66
+ /** Link destination as written in HTML (relative path, only for <a> elements, empty string for buttons) */
67
+ href: string;
68
+ /** Additional element attributes in key:value format (e.g., ['data-category:val', 'data-campaign:val2']) */
69
+ attributes: string[];
70
+ };
71
+ /**
72
+ * Partial content impression data sent by producer plugins.
73
+ * Contains only impression-specific data (content and position).
74
+ * The enricher plugin will add page data automatically.
75
+ */
76
+ export type DotCMSContentImpressionPayload = {
77
+ /** Content information */
78
+ content: {
79
+ /** Content identifier */
80
+ identifier: string;
81
+ /** Content inode */
82
+ inode: string;
83
+ /** Content title */
84
+ title: string;
85
+ /** Content type name */
86
+ content_type: string;
87
+ };
88
+ /** Position information in the viewport and DOM */
89
+ position: {
90
+ /** Viewport offset percentage from top */
91
+ viewport_offset_pct: number;
92
+ /** DOM index position */
93
+ dom_index: number;
94
+ };
95
+ };
96
+ /**
97
+ * Partial content click data sent by producer plugins.
98
+ * Extends impression payload with element metadata.
99
+ */
100
+ export type DotCMSContentClickPayload = DotCMSContentImpressionPayload & {
101
+ /** Clicked element information */
102
+ element: DotCMSElementData;
103
+ };
104
+ /**
105
+ * Conversion payload sent when tracking conversions.
106
+ * Contains conversion name and optional custom data.
107
+ */
108
+ export type DotCMSConversionPayload = {
109
+ /** Name of the conversion event */
110
+ name: string;
111
+ /** Optional custom user data (any valid JSON) */
112
+ custom?: JsonObject;
113
+ };
114
+ /**
115
+ * Complete data structure for content impression events after enrichment.
116
+ * Includes minimal page data (title and url) added by the enricher plugin.
117
+ */
118
+ export type DotCMSContentImpressionEventData = DotCMSContentImpressionPayload & {
119
+ /** Minimal page data where the impression occurred (added by enricher) */
120
+ page: DotCMSContentImpressionPageData;
121
+ };
122
+ /**
123
+ * Complete data structure for content click events after enrichment.
124
+ * Includes minimal page data (title and url) added by the enricher plugin.
125
+ */
126
+ export type DotCMSContentClickEventData = DotCMSContentClickPayload & {
127
+ /** Minimal page data where the click occurred (added by enricher) */
128
+ page: DotCMSContentImpressionPageData;
129
+ };
130
+ /**
131
+ * Complete data structure for conversion events after enrichment.
132
+ * Includes page data added by the enricher plugin.
133
+ */
134
+ export type DotCMSConversionEventData = {
135
+ /** Conversion information */
136
+ conversion: {
137
+ /** Name of the user-defined conversion */
138
+ name: string;
139
+ };
140
+ /** Page data where the conversion occurred (added by enricher) */
141
+ page: DotCMSContentImpressionPageData;
142
+ /** Optional custom user data (any valid JSON) */
143
+ custom?: JsonObject;
144
+ };
53
145
  /**
54
146
  * Pageview event structure.
55
147
  */
56
148
  export type DotCMSPageViewEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.PAGEVIEW, DotCMSPageViewEventData>;
149
+ /**
150
+ * Content impression event structure.
151
+ */
152
+ export type DotCMSContentImpressionEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.CONTENT_IMPRESSION, DotCMSContentImpressionEventData>;
153
+ /**
154
+ * Content click event structure.
155
+ */
156
+ export type DotCMSContentClickEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.CONTENT_CLICK, DotCMSContentClickEventData>;
157
+ /**
158
+ * Conversion event structure.
159
+ */
160
+ export type DotCMSConversionEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.CONVERSION, DotCMSConversionEventData>;
57
161
  /**
58
162
  * Custom event structure.
59
163
  */
60
164
  export type DotCMSCustomEvent = DotCMSEventBase<DotCMSCustomEventType, DotCMSCustomEventData>;
61
165
  /**
62
166
  * Union type for all possible analytics events.
167
+ * Used primarily for type documentation and validation.
63
168
  */
64
- export type DotCMSEvent = DotCMSPageViewEvent | DotCMSCustomEvent;
169
+ export type DotCMSEvent = DotCMSPageViewEvent | DotCMSContentImpressionEvent | DotCMSContentClickEvent | DotCMSConversionEvent | DotCMSCustomEvent;
@@ -1,7 +1,7 @@
1
- import { DotCMSAnalyticsEventContext, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
2
- import { JsonObject } from './event.model';
1
+ import { DotCMSAnalyticsEventContext, DotCMSContentImpressionPageData, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
2
+ import { DotCMSContentImpressionPayload, JsonObject } from './event.model';
3
3
  import { DotCMSAnalyticsRequestBody } from './request.model';
4
- import { DotCMSCustomEventType } from '../constants';
4
+ import { LogLevel } from '../dot-analytics.logger';
5
5
  /**
6
6
  * Configuration for event queue management.
7
7
  * Controls how events are batched before sending to the server.
@@ -12,22 +12,62 @@ export interface QueueConfig {
12
12
  /** Time in milliseconds between flushes - sends pending events (default: 5000) */
13
13
  flushInterval?: number;
14
14
  }
15
+ /**
16
+ * Configuration for content impression tracking.
17
+ * Controls how content visibility is detected and tracked.
18
+ */
19
+ export interface ImpressionConfig {
20
+ /** Minimum percentage of element visible (0.0 to 1.0) - default: 0.5 */
21
+ visibilityThreshold?: number;
22
+ /** Minimum time in milliseconds element must be visible - default: 750 */
23
+ dwellMs?: number;
24
+ /** Maximum number of elements to track (performance limit) - default: 1000 */
25
+ maxNodes?: number;
26
+ /** Throttle time in milliseconds for intersection callbacks - default: 100 */
27
+ throttleMs?: number;
28
+ }
29
+ /**
30
+ * Interface for contentlet data extracted from DOM elements
31
+ */
32
+ export interface ContentletData {
33
+ identifier: string;
34
+ inode: string;
35
+ contentType: string;
36
+ title: string;
37
+ baseType: string;
38
+ }
39
+ /**
40
+ * Interface for viewport metrics
41
+ */
42
+ export interface ViewportMetrics {
43
+ offsetPercentage: number;
44
+ visibilityRatio: number;
45
+ }
15
46
  /**
16
47
  * Main interface for the DotCMS Analytics SDK.
17
- * Provides the core methods for tracking page views and custom events.
48
+ * Provides the core methods for tracking page views, custom events, and conversions.
18
49
  */
19
50
  export interface DotCMSAnalytics {
20
51
  /**
21
52
  * Track a page view event.
22
53
  * @param payload - Optional custom data to include with the page view (any valid JSON object)
23
54
  */
24
- pageView: (payload?: JsonObject) => void;
55
+ pageView(): void;
56
+ pageView(payload: JsonObject): void;
25
57
  /**
26
58
  * Track a custom event.
27
59
  * @param eventName - The name/type of the event to track
28
60
  * @param payload - Custom data to include with the event (any valid JSON object)
29
61
  */
30
- track: (eventName: string, payload: JsonObject) => void;
62
+ track(eventName: string): void;
63
+ track(eventName: string, payload: JsonObject): void;
64
+ /**
65
+ * Track a conversion event.
66
+ * @param name - Name of the conversion (e.g., 'purchase', 'download', 'signup')
67
+ * @param options - Optional custom data and element information
68
+ */
69
+ conversion(name: string): void;
70
+ conversion(name: string, options: JsonObject): void;
31
71
  }
32
72
  /**
33
73
  * Configuration interface for DotCMS Analytics SDK.
@@ -42,6 +82,16 @@ export interface DotCMSAnalyticsConfig {
42
82
  * Enable debug mode to get additional logging information.
43
83
  */
44
84
  debug: boolean;
85
+ /**
86
+ * Set the minimum log level for console output.
87
+ * - 'debug': Show all logs including detailed debugging information
88
+ * - 'info': Show informational messages, warnings, and errors
89
+ * - 'warn': Show only warnings and errors
90
+ * - 'error': Show only errors
91
+ *
92
+ * If not specified, falls back to debug flag (debug=true → 'debug', debug=false → 'warn')
93
+ */
94
+ logLevel?: LogLevel;
45
95
  /**
46
96
  * Automatically track page views when set to true.
47
97
  */
@@ -57,15 +107,28 @@ export interface DotCMSAnalyticsConfig {
57
107
  * - `QueueConfig`: Enable queuing with custom settings
58
108
  */
59
109
  queue?: QueueConfig | boolean;
110
+ /**
111
+ * Content impression tracking configuration (default: undefined - disabled):
112
+ * - `undefined` or `false`: Impression tracking disabled
113
+ * - `true`: Enable with default settings (threshold: 0.5, dwell: 750ms, maxNodes: 1000)
114
+ * - `ImpressionConfig`: Enable with custom settings
115
+ */
116
+ impressions?: ImpressionConfig | boolean;
117
+ /**
118
+ * Content click tracking configuration (default: undefined - disabled):
119
+ * - `undefined` or `false`: Click tracking disabled
120
+ * - `true`: Enable click tracking
121
+ */
122
+ clicks?: boolean;
60
123
  }
61
124
  /**
62
125
  * Track event payload with context.
63
- * This is the payload for custom track events after the identity plugin adds context.
126
+ * This is the payload for track events after the identity plugin adds context.
64
127
  * Used in the track:dot-analytics enricher plugin.
65
128
  */
66
129
  export interface AnalyticsTrackPayloadWithContext extends AnalyticsBasePayload {
67
- /** The custom event name (any string except 'pageview') */
68
- event: DotCMSCustomEventType;
130
+ /** The event name (can be predefined or custom) */
131
+ event: string;
69
132
  /** Analytics context added by identity plugin */
70
133
  context: DotCMSAnalyticsEventContext;
71
134
  }
@@ -84,29 +147,16 @@ type AnalyticsBasePayloadType = 'page' | 'track';
84
147
  * Analytics.js hook parameter types for DotCMS.
85
148
  * Represents the payload structure used by Analytics.js lifecycle hooks
86
149
  * for intercepting and modifying analytics events.
150
+ *
151
+ * Properties are flexible (Record<string, unknown>) to support both:
152
+ * - Page events: with page-specific fields (title, url, path, etc.)
153
+ * - Track events: with any custom event data structure
87
154
  */
88
155
  export interface AnalyticsBasePayload {
89
156
  /** The type of analytics event */
90
157
  type: AnalyticsBasePayloadType;
91
- /** Properties associated with the event */
92
- properties: {
93
- /** Page title */
94
- title: string;
95
- /** Page URL */
96
- url: string;
97
- /** Page path */
98
- path: string;
99
- /** URL hash fragment */
100
- hash: string;
101
- /** URL search parameters */
102
- search: string;
103
- /** Viewport width */
104
- width: number;
105
- /** Viewport height */
106
- height: number;
107
- /** Referrer URL */
108
- referrer?: string;
109
- };
158
+ /** Properties associated with the event (flexible structure) */
159
+ properties: Record<string, unknown>;
110
160
  /** Configuration options for the event */
111
161
  options: Record<string, unknown>;
112
162
  /** User identifier */
@@ -146,6 +196,17 @@ export type EnrichedAnalyticsPayload = AnalyticsBasePayloadWithContext & {
146
196
  /** Local timestamp when the event occurred */
147
197
  local_time: string;
148
198
  };
199
+ /**
200
+ * Enriched track event payload with fields added to root based on event type.
201
+ * Used by the enricher plugin for track events.
202
+ */
203
+ export interface EnrichedTrackPayload extends AnalyticsTrackPayloadWithContext {
204
+ local_time: string;
205
+ page?: DotCMSContentImpressionPageData | DotCMSEventPageData;
206
+ content?: DotCMSContentImpressionPayload['content'];
207
+ position?: DotCMSContentImpressionPayload['position'];
208
+ utm?: DotCMSEventUtmData;
209
+ }
149
210
  /**
150
211
  * Analytics.js instance structure for DotCMS.
151
212
  * Represents the internal structure of an Analytics.js instance,
@@ -1,24 +1,32 @@
1
1
  import { DotCMSAnalyticsEventContext } from './data.model';
2
- import { DotCMSCustomEvent, DotCMSEvent, DotCMSPageViewEvent } from './event.model';
2
+ import { DotCMSEvent } from './event.model';
3
3
  /**
4
4
  * Analytics request body for DotCMS Analytics.
5
5
  * Generic structure sent to the DotCMS analytics server.
6
+ *
7
+ * This structure contains properly typed events that match the DotCMS event specifications.
8
+ * Events can be pageviews, content impressions, or custom events, each with their own data structure.
6
9
  */
7
- export interface DotCMSRequestBody<T extends DotCMSEvent> {
10
+ export interface DotCMSRequestBody {
8
11
  /** Context information shared across all events */
9
12
  context: DotCMSAnalyticsEventContext;
10
13
  /** Array of analytics events to be tracked */
11
- events: T[];
14
+ events: DotCMSEvent[];
12
15
  }
13
16
  /**
14
- * Specific request body type for PageView events
17
+ * Main type for analytics request bodies.
18
+ * Flexible enough to accept any event type (pageview, content_impression, custom, etc.)
15
19
  */
16
- export type DotCMSPageViewRequestBody = DotCMSRequestBody<DotCMSPageViewEvent>;
20
+ export type DotCMSAnalyticsRequestBody = DotCMSRequestBody;
17
21
  /**
18
- * Specific request body type for Custom events
22
+ * Specific request body type for PageView events (for type documentation)
19
23
  */
20
- export type DotCMSCustomEventRequestBody = DotCMSRequestBody<DotCMSCustomEvent>;
24
+ export type DotCMSPageViewRequestBody = DotCMSRequestBody;
21
25
  /**
22
- * Union type for all possible request bodies
26
+ * Specific request body type for ContentImpression events (for type documentation)
23
27
  */
24
- export type DotCMSAnalyticsRequestBody = DotCMSPageViewRequestBody | DotCMSCustomEventRequestBody;
28
+ export type DotCMSContentImpressionRequestBody = DotCMSRequestBody;
29
+ /**
30
+ * Specific request body type for Custom events (for type documentation)
31
+ */
32
+ export type DotCMSCustomEventRequestBody = DotCMSRequestBody;