@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.
- package/README.md +314 -9
- package/lib/core/dot-analytics.content.js +84 -0
- package/lib/core/plugin/click/dot-analytics.click-tracker.d.ts +108 -0
- package/lib/core/plugin/click/dot-analytics.click-tracker.js +144 -0
- package/lib/core/plugin/click/dot-analytics.click.plugin.d.ts +36 -0
- package/lib/core/plugin/click/dot-analytics.click.plugin.js +27 -0
- package/lib/core/plugin/click/dot-analytics.click.utils.d.ts +12 -0
- package/lib/core/plugin/click/dot-analytics.click.utils.js +55 -0
- package/lib/core/plugin/enricher/dot-analytics.enricher.plugin.d.ts +14 -10
- package/lib/core/plugin/enricher/dot-analytics.enricher.plugin.js +26 -38
- package/lib/core/{shared/dot-content-analytics.activity-tracker.d.ts → plugin/identity/dot-analytics.identity.activity-tracker.d.ts} +2 -17
- package/lib/core/{shared/dot-content-analytics.activity-tracker.js → plugin/identity/dot-analytics.identity.activity-tracker.js} +17 -38
- package/lib/core/plugin/identity/dot-analytics.identity.plugin.d.ts +2 -20
- package/lib/core/plugin/identity/dot-analytics.identity.plugin.js +7 -7
- package/lib/core/plugin/identity/dot-analytics.identity.utils.d.ts +0 -16
- package/lib/core/plugin/impression/dot-analytics.impression-tracker.d.ts +62 -0
- package/lib/core/plugin/impression/dot-analytics.impression-tracker.js +202 -0
- package/lib/core/plugin/impression/dot-analytics.impression.plugin.d.ts +40 -0
- package/lib/core/plugin/impression/dot-analytics.impression.plugin.js +27 -0
- package/lib/core/plugin/impression/dot-analytics.impression.utils.d.ts +26 -0
- package/lib/core/plugin/impression/dot-analytics.impression.utils.js +27 -0
- package/lib/core/plugin/impression/index.d.ts +2 -0
- package/lib/core/plugin/main/dot-analytics.plugin.d.ts +46 -0
- package/lib/core/plugin/main/dot-analytics.plugin.js +129 -0
- package/lib/core/shared/constants/{dot-content-analytics.constants.d.ts → dot-analytics.constants.d.ts} +62 -0
- package/lib/core/shared/constants/dot-analytics.constants.js +53 -0
- package/lib/core/shared/constants/index.d.ts +1 -1
- package/lib/core/shared/dot-analytics.logger.d.ts +85 -0
- package/lib/core/shared/dot-analytics.logger.js +90 -0
- package/lib/core/shared/http/dot-analytics.http.d.ts +9 -0
- package/lib/core/shared/http/dot-analytics.http.js +34 -0
- package/lib/core/shared/models/data.model.d.ts +39 -1
- package/lib/core/shared/models/event.model.d.ts +108 -3
- package/lib/core/shared/models/library.model.d.ts +89 -28
- package/lib/core/shared/models/request.model.d.ts +17 -9
- package/lib/core/shared/queue/dot-analytics.queue.utils.js +47 -40
- package/lib/core/shared/{dot-content-analytics.utils.d.ts → utils/dot-analytics.utils.d.ts} +91 -3
- package/lib/core/shared/utils/dot-analytics.utils.js +200 -0
- package/lib/react/hook/useContentAnalytics.js +17 -11
- package/lib/react/hook/useRouterTracker.js +12 -12
- package/lib/react/internal/utils.js +1 -1
- package/package.json +7 -6
- package/uve/src/internal/events.js +30 -31
- package/uve/src/lib/dom/dom.utils.js +46 -52
- package/lib/core/dot-content-analytics.js +0 -46
- package/lib/core/plugin/dot-analytics.plugin.d.ts +0 -33
- package/lib/core/plugin/dot-analytics.plugin.js +0 -42
- package/lib/core/shared/constants/dot-content-analytics.constants.js +0 -34
- package/lib/core/shared/dot-content-analytics.http.d.ts +0 -17
- package/lib/core/shared/dot-content-analytics.http.js +0 -41
- package/lib/core/shared/dot-content-analytics.utils.js +0 -147
- /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
|
+
};
|
|
@@ -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-
|
|
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 {
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
68
|
-
event:
|
|
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 {
|
|
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
|
|
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:
|
|
14
|
+
events: DotCMSEvent[];
|
|
12
15
|
}
|
|
13
16
|
/**
|
|
14
|
-
*
|
|
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
|
|
20
|
+
export type DotCMSAnalyticsRequestBody = DotCMSRequestBody;
|
|
17
21
|
/**
|
|
18
|
-
* Specific request body type for
|
|
22
|
+
* Specific request body type for PageView events (for type documentation)
|
|
19
23
|
*/
|
|
20
|
-
export type
|
|
24
|
+
export type DotCMSPageViewRequestBody = DotCMSRequestBody;
|
|
21
25
|
/**
|
|
22
|
-
*
|
|
26
|
+
* Specific request body type for ContentImpression events (for type documentation)
|
|
23
27
|
*/
|
|
24
|
-
export type
|
|
28
|
+
export type DotCMSContentImpressionRequestBody = DotCMSRequestBody;
|
|
29
|
+
/**
|
|
30
|
+
* Specific request body type for Custom events (for type documentation)
|
|
31
|
+
*/
|
|
32
|
+
export type DotCMSCustomEventRequestBody = DotCMSRequestBody;
|