@dotcms/analytics 1.1.1 → 1.2.0

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 (40) hide show
  1. package/README.md +284 -71
  2. package/lib/core/dot-content-analytics.d.ts +8 -1
  3. package/lib/core/dot-content-analytics.js +26 -23
  4. package/lib/core/plugin/dot-analytics.plugin.d.ts +8 -7
  5. package/lib/core/plugin/dot-analytics.plugin.js +25 -62
  6. package/lib/core/plugin/enricher/dot-analytics.enricher.plugin.d.ts +12 -28
  7. package/lib/core/plugin/enricher/dot-analytics.enricher.plugin.js +37 -15
  8. package/lib/core/plugin/identity/dot-analytics.identity.plugin.d.ts +11 -11
  9. package/lib/core/plugin/identity/dot-analytics.identity.plugin.js +13 -11
  10. package/lib/core/plugin/identity/dot-analytics.identity.utils.d.ts +7 -6
  11. package/lib/core/shared/constants/dot-content-analytics.constants.d.ts +70 -0
  12. package/lib/core/shared/constants/dot-content-analytics.constants.js +34 -0
  13. package/lib/core/shared/constants/index.d.ts +4 -0
  14. package/lib/core/shared/dot-content-analytics.activity-tracker.d.ts +9 -2
  15. package/lib/core/shared/dot-content-analytics.activity-tracker.js +11 -10
  16. package/lib/core/shared/dot-content-analytics.http.d.ts +13 -4
  17. package/lib/core/shared/dot-content-analytics.http.js +25 -13
  18. package/lib/core/shared/dot-content-analytics.utils.d.ts +105 -44
  19. package/lib/core/shared/dot-content-analytics.utils.js +92 -68
  20. package/lib/core/shared/models/data.model.d.ts +103 -0
  21. package/lib/core/shared/models/event.model.d.ts +64 -0
  22. package/lib/core/shared/models/index.d.ts +7 -0
  23. package/lib/core/shared/models/library.model.d.ts +191 -0
  24. package/lib/core/shared/models/request.model.d.ts +24 -0
  25. package/lib/core/shared/queue/dot-analytics.queue.utils.d.ts +28 -0
  26. package/lib/core/shared/queue/dot-analytics.queue.utils.js +73 -0
  27. package/lib/core/shared/queue/index.d.ts +1 -0
  28. package/lib/react/components/DotContentAnalytics.d.ts +1 -1
  29. package/lib/react/hook/useContentAnalytics.d.ts +43 -15
  30. package/lib/react/hook/useContentAnalytics.js +18 -21
  31. package/lib/react/hook/useRouterTracker.d.ts +1 -1
  32. package/lib/react/internal/utils.d.ts +1 -1
  33. package/lib/react/internal/utils.js +2 -2
  34. package/lib/react/public-api.d.ts +1 -1
  35. package/lib/standalone.d.ts +2 -2
  36. package/package.json +2 -1
  37. package/uve/src/internal/constants.js +8 -3
  38. package/lib/core/shared/dot-content-analytics.constants.d.ts +0 -37
  39. package/lib/core/shared/dot-content-analytics.constants.js +0 -14
  40. package/lib/core/shared/dot-content-analytics.model.d.ts +0 -351
@@ -1,8 +1,26 @@
1
1
  import { PageData } from 'analytics';
2
- import { DotCMSAnalyticsConfig, DotCMSAnalyticsContext, DotCMSAnalyticsPayload, DotCMSBrowserEventData, DotCMSDeviceData, DotCMSPageData, DotCMSUtmData } from './dot-content-analytics.model';
2
+ import { AnalyticsBasePayloadWithContext, DotCMSAnalyticsConfig, DotCMSAnalyticsEventContext, DotCMSBrowserData, DotCMSEventDeviceData, DotCMSEventUtmData, EnrichedAnalyticsPayload } from './models';
3
3
  export { cleanupActivityTracking, getLastActivity, getSessionInfo, initializeActivityTracking, isUserInactive, updateSessionActivity } from './dot-content-analytics.activity-tracker';
4
4
  /**
5
- * Generates a cryptographically secure random ID
5
+ * Validates required configuration fields for Analytics initialization.
6
+ *
7
+ * @param config - The analytics configuration to validate
8
+ * @returns Array of missing field names, or null if all required fields are present
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * const missing = validateAnalyticsConfig(config);
13
+ * if (missing) {
14
+ * console.error(`Missing: ${missing.join(' and ')}`);
15
+ * }
16
+ * ```
17
+ */
18
+ export declare function validateAnalyticsConfig(config: DotCMSAnalyticsConfig): string[] | null;
19
+ /**
20
+ * Generates a cryptographically secure random ID.
21
+ * @internal This function is for internal use only and should not be used outside of the SDK.
22
+ * @param prefix - The prefix for the generated ID
23
+ * @returns A unique ID string with the given prefix
6
24
  */
7
25
  export declare const generateSecureId: (prefix: string) => string;
8
26
  /**
@@ -13,23 +31,31 @@ export declare const safeSessionStorage: {
13
31
  setItem: (key: string, value: string) => void;
14
32
  };
15
33
  /**
16
- * Gets or generates a user ID
34
+ * Gets or generates a user ID from localStorage.
35
+ * @internal This function is for internal use only.
36
+ * @returns The user ID string
17
37
  */
18
38
  export declare const getUserId: () => string;
19
39
  /**
20
- * Gets session ID with comprehensive lifecycle management
21
- * Returns existing valid session ID or creates a new one if needed
40
+ * Gets session ID with comprehensive lifecycle management.
41
+ * Returns existing valid session ID or creates a new one if needed.
42
+ * @internal This function is for internal use only.
22
43
  *
23
44
  * Session validation criteria:
24
45
  * 1. User is still active (< 30 min inactivity)
25
46
  * 2. Session hasn't passed midnight (UTC)
26
- * 3. UTM parameters haven't changed
47
+ *
48
+ * @returns The session ID string
27
49
  */
28
50
  export declare const getSessionId: () => string;
29
51
  /**
30
- * Gets analytics context with user and session identification
52
+ * Gets analytics context with user and session identification.
53
+ * Used by the identity plugin to inject context into analytics events.
54
+ *
55
+ * @param config - The analytics configuration object
56
+ * @returns The analytics context with site_key, session_id, and user_id
31
57
  */
32
- export declare const getAnalyticsContext: (config: DotCMSAnalyticsConfig) => DotCMSAnalyticsContext;
58
+ export declare const getAnalyticsContext: (config: DotCMSAnalyticsConfig) => DotCMSAnalyticsEventContext;
33
59
  /**
34
60
  * Configuration result with warnings for analytics setup
35
61
  */
@@ -40,72 +66,107 @@ export interface AnalyticsConfigResult {
40
66
  hasIssues: boolean;
41
67
  }
42
68
  /**
43
- * Gets analytics configuration, always returns a config (with defaults if needed)
69
+ * Gets analytics configuration from script tag attributes.
70
+ * Always returns a config (with defaults if needed).
71
+ *
44
72
  * - If no data-analytics-server attribute is found, uses the current domain as the server endpoint
45
73
  * - Both debug and autoPageView default to false (must be explicitly set to "true")
74
+ *
75
+ * @returns The analytics configuration object
46
76
  */
47
77
  export declare const getAnalyticsConfig: () => DotCMSAnalyticsConfig;
78
+ /**
79
+ * Gets current device data for analytics.
80
+ * Combines static browser data with dynamic viewport information.
81
+ * Used by the identity plugin to inject device data into context.
82
+ *
83
+ * @returns Device data with screen resolution, language, and viewport dimensions
84
+ */
85
+ export declare const getDeviceDataForContext: () => DotCMSEventDeviceData;
48
86
  /**
49
87
  * Retrieves the browser event data - optimized but accurate.
88
+ * @internal This function is for internal use only.
89
+ * @param location - The Location object to extract data from
90
+ * @returns Browser event data with all relevant information
50
91
  */
51
- export declare const getBrowserEventData: (location: Location) => DotCMSBrowserEventData;
92
+ export declare const getBrowserEventData: (location: Location) => DotCMSBrowserData;
52
93
  /**
53
- * Extracts UTM parameters from the URL - cached for performance
94
+ * Extracts and transforms UTM parameters from the URL - cached for performance.
95
+ * Returns UTM data in DotCMS format (without 'utm_' prefix).
96
+ * @internal This function is for internal use only.
97
+ * @param location - The Location object to extract UTM parameters from
98
+ * @returns DotCMSEventUtmData object with transformed UTM parameters (source, medium, campaign, etc.)
54
99
  */
55
- export declare const extractUTMParameters: (location: Location) => Record<string, string>;
100
+ export declare const extractUTMParameters: (location: Location) => DotCMSEventUtmData;
56
101
  /**
57
- * Default redirect function
102
+ * Default redirect function.
103
+ * @internal This function is for internal use only.
104
+ * @param href - The URL to redirect to
58
105
  */
59
106
  export declare const defaultRedirectFn: (href: string) => string;
60
107
  /**
61
- * Gets local time in ISO format without milliseconds
108
+ * Gets local time in ISO format without milliseconds.
109
+ * Used by enricher plugins to add local_time to events.
110
+ *
111
+ * @returns Local time string in ISO 8601 format with timezone offset (e.g., "2024-01-01T12:00:00-05:00")
62
112
  */
63
113
  export declare const getLocalTime: () => string;
64
114
  /**
65
- * Gets page data from browser event data and payload
115
+ * Gets page data from browser event data and payload.
116
+ * @internal This function is for internal use only.
117
+ * @param browserData - Browser event data
118
+ * @param payload - Payload with properties
119
+ * @returns PageData object for Analytics.js
66
120
  */
67
- export declare const getPageData: (browserData: DotCMSBrowserEventData, payload: DotCMSAnalyticsPayload) => PageData;
121
+ export declare const getPageData: (browserData: DotCMSBrowserData, payload: {
122
+ properties: Record<string, unknown>;
123
+ }) => PageData;
68
124
  /**
69
- * Gets device data from browser event data
125
+ * Gets device data from browser event data.
126
+ * @internal This function is for internal use only.
127
+ * @param browserData - Browser event data
128
+ * @returns Device data with screen resolution, language, and viewport dimensions
70
129
  */
71
- export declare const getDeviceData: (browserData: DotCMSBrowserEventData) => DotCMSDeviceData;
130
+ export declare const getDeviceData: (browserData: DotCMSBrowserData) => DotCMSEventDeviceData;
72
131
  /**
73
- * Gets UTM data from browser event data
132
+ * Gets UTM data from browser event data.
133
+ * @internal This function is for internal use only.
134
+ * @param browserData - Browser event data
135
+ * @returns UTM data with source, medium, campaign, etc.
74
136
  */
75
- export declare const getUtmData: (browserData: DotCMSBrowserEventData) => DotCMSUtmData;
137
+ export declare const getUtmData: (browserData: DotCMSBrowserData) => DotCMSEventUtmData;
76
138
  /**
77
- * Enriches payload with UTM data
139
+ * Enriches payload with UTM data.
140
+ * @internal This function is for internal use only.
141
+ * @param payload - The payload to enrich
142
+ * @returns The payload with UTM data added
78
143
  */
79
- export declare const enrichWithUtmData: (payload: DotCMSAnalyticsPayload) => DotCMSAnalyticsPayload;
144
+ export declare const enrichWithUtmData: <T extends Record<string, unknown>>(payload: T) => T;
80
145
  /**
81
- * Optimized payload enrichment using existing analytics.js data
82
- * Reuses payload.properties data instead of recalculating from DOM when available
83
- * Maintains the same output structure as the original function
146
+ * Optimized payload enrichment using existing analytics.js data.
147
+ * Filters out Analytics.js default properties and only keeps user-provided properties in custom.
148
+ * Used by the enricher plugin to transform Analytics.js payload into DotCMS event format.
149
+ *
150
+ * @param payload - The Analytics.js payload with context already injected by identity plugin
151
+ * @param location - The Location object to extract page data from (defaults to window.location)
152
+ * @returns Enriched payload with page, UTM, custom data, and local_time (device is in context)
84
153
  */
85
- export declare const enrichPagePayloadOptimized: (payload: DotCMSAnalyticsPayload, location?: Location) => {
86
- local_time: string;
87
- utm?: DotCMSUtmData;
88
- page: DotCMSPageData;
89
- device: DotCMSDeviceData;
90
- event: string;
91
- properties: Record<string, unknown>;
92
- options: Record<string, unknown>;
93
- context?: DotCMSAnalyticsContext;
94
- };
154
+ export declare const enrichPagePayloadOptimized: (payload: AnalyticsBasePayloadWithContext, location?: Location) => EnrichedAnalyticsPayload;
95
155
  /**
96
- * @deprecated Use enrichPagePayloadOptimized instead to avoid data duplication
97
- * Legacy function that enriches page payload with all data in one call
98
- * This function duplicates data already available in analytics.js payload
156
+ * Legacy function that enriches page payload with all data in one call.
157
+ * @internal This function is for internal use only.
158
+ * @param payload - The payload to enrich
159
+ * @param location - The Location object to extract data from
160
+ * @returns Object with enriched payload
99
161
  */
100
- export declare const enrichPagePayload: (payload: DotCMSAnalyticsPayload, location?: Location) => {
162
+ export declare const enrichPagePayload: (payload: {
163
+ properties: Record<string, unknown>;
164
+ } & Record<string, unknown>, location?: Location) => {
101
165
  payload: {
102
166
  local_time: string;
103
- utm?: DotCMSUtmData;
167
+ utm?: DotCMSEventUtmData | undefined;
104
168
  page: PageData;
105
- device: DotCMSDeviceData;
106
- event: string;
169
+ device: DotCMSEventDeviceData;
107
170
  properties: Record<string, unknown>;
108
- options: Record<string, unknown>;
109
- context?: DotCMSAnalyticsContext;
110
171
  };
111
172
  };
@@ -1,9 +1,15 @@
1
- import { SESSION_STORAGE_KEY as h, DEFAULT_SESSION_TIMEOUT_MINUTES as S, USER_ID_KEY as m } from "./dot-content-analytics.constants.js";
2
- let d = null;
3
- const u = (t) => {
4
- const e = Date.now(), n = Math.random().toString(36).substr(2, 9), o = Math.random().toString(36).substr(2, 9);
5
- return `${t}_${e}_${n}${o}`;
6
- }, l = {
1
+ import { ANALYTICS_JS_DEFAULT_PROPERTIES as f, SESSION_STORAGE_KEY as h, DEFAULT_SESSION_TIMEOUT_MINUTES as w, USER_ID_KEY as l, EXPECTED_UTM_KEYS as _ } from "./constants/dot-content-analytics.constants.js";
2
+ import "../../../uve/src/internal/constants.js";
3
+ function U(t) {
4
+ var n, s;
5
+ const e = [];
6
+ return (n = t.siteAuth) != null && n.trim() || e.push('"siteAuth"'), (s = t.server) != null && s.trim() || e.push('"server"'), e.length > 0 ? e : null;
7
+ }
8
+ let u = null, g = null;
9
+ const d = (t) => {
10
+ const e = Date.now(), n = Math.random().toString(36).substr(2, 9), s = Math.random().toString(36).substr(2, 9);
11
+ return `${t}_${e}_${n}${s}`;
12
+ }, m = {
7
13
  getItem: (t) => {
8
14
  try {
9
15
  return localStorage.getItem(t);
@@ -15,109 +21,127 @@ const u = (t) => {
15
21
  try {
16
22
  localStorage.setItem(t, e);
17
23
  } catch {
18
- console.warn(`DotAnalytics: Could not save ${t} to localStorage`);
24
+ console.warn(`DotCMS Analytics: Could not save ${t} to localStorage`);
19
25
  }
20
26
  }
21
- }, f = () => {
22
- let t = l.getItem(m);
23
- return t || (t = u("user"), l.setItem(m, t)), t;
24
- }, _ = (t) => {
25
- const e = new Date(t), n = /* @__PURE__ */ new Date(), o = new Date(
27
+ }, p = () => {
28
+ let t = m.getItem(l);
29
+ return t || (t = d("user"), m.setItem(l, t)), t;
30
+ }, D = (t) => {
31
+ const e = new Date(t), n = /* @__PURE__ */ new Date(), s = new Date(
26
32
  e.getUTCFullYear(),
27
33
  e.getUTCMonth(),
28
34
  e.getUTCDate()
29
- ), s = new Date(n.getUTCFullYear(), n.getUTCMonth(), n.getUTCDate());
30
- return o.getTime() !== s.getTime();
31
- }, p = () => {
35
+ ), o = new Date(n.getUTCFullYear(), n.getUTCMonth(), n.getUTCDate());
36
+ return s.getTime() !== o.getTime();
37
+ }, T = () => {
32
38
  const t = Date.now();
33
39
  if (typeof window > "u")
34
- return u("session_fallback");
40
+ return d("session_fallback");
35
41
  try {
36
42
  const e = sessionStorage.getItem(h);
37
43
  if (e) {
38
- const { sessionId: s, startTime: c, lastActivity: i } = JSON.parse(e), g = !_(c), a = t - i < S * 60 * 1e3;
39
- if (g && a)
44
+ const { sessionId: o, startTime: r, lastActivity: a } = JSON.parse(e), c = !D(r), i = t - a < w * 60 * 1e3;
45
+ if (c && i)
40
46
  return sessionStorage.setItem(
41
47
  h,
42
48
  JSON.stringify({
43
- sessionId: s,
44
- startTime: c,
49
+ sessionId: o,
50
+ startTime: r,
45
51
  lastActivity: t
46
52
  })
47
- ), s;
53
+ ), o;
48
54
  }
49
- const n = u("session"), o = {
55
+ const n = d("session"), s = {
50
56
  sessionId: n,
51
57
  startTime: t,
52
58
  lastActivity: t
53
59
  };
54
- return sessionStorage.setItem(h, JSON.stringify(o)), n;
60
+ return sessionStorage.setItem(h, JSON.stringify(s)), n;
55
61
  } catch {
56
- return u("session_fallback");
62
+ return d("session_fallback");
57
63
  }
58
- }, T = (t) => {
59
- const e = p(), n = f();
60
- return t.debug && console.warn("DotAnalytics Identity Context:", {
64
+ }, $ = (t) => {
65
+ const e = T(), n = p(), s = I();
66
+ return t.debug && console.warn("DotCMS Analytics Identity Context:", {
61
67
  sessionId: e,
62
68
  userId: n
63
69
  }), {
64
- site_key: t.siteKey,
70
+ site_auth: t.siteAuth,
65
71
  session_id: e,
66
- user_id: n
72
+ user_id: n,
73
+ device: s
74
+ };
75
+ }, S = () => u || (u = {
76
+ user_language: navigator.language,
77
+ doc_encoding: document.characterSet || document.charset,
78
+ screen_resolution: typeof screen < "u" && screen.width && screen.height ? `${screen.width}x${screen.height}` : ""
79
+ }, u), I = () => {
80
+ const t = S(), e = window.innerWidth || document.documentElement.clientWidth || 0, n = window.innerHeight || document.documentElement.clientHeight || 0;
81
+ return {
82
+ screen_resolution: t.screen_resolution ?? "",
83
+ language: t.user_language ?? "",
84
+ viewport_width: String(e),
85
+ viewport_height: String(n)
67
86
  };
68
- }, w = () => d || (d = {
69
- user_language: navigator.language || void 0,
70
- doc_encoding: document.characterSet || document.charset || void 0,
71
- screen_resolution: typeof screen < "u" && screen.width && screen.height ? `${screen.width}x${screen.height}` : void 0
72
- }, d), I = () => {
87
+ }, y = (t) => {
88
+ const e = t.search;
89
+ if (g && g.search === e)
90
+ return g.params;
91
+ const n = new URLSearchParams(e), s = {};
92
+ return _.forEach((o) => {
93
+ const r = n.get(o);
94
+ if (r) {
95
+ const a = o.replace("utm_", "");
96
+ s[a] = r;
97
+ }
98
+ }), g = { search: e, params: s }, s;
99
+ }, E = () => {
73
100
  try {
74
- const t = (/* @__PURE__ */ new Date()).getTimezoneOffset(), e = t > 0 ? "-" : "+", n = Math.abs(t), o = Math.floor(n / 60), s = n % 60;
75
- return `${e}${o.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}`;
101
+ const t = (/* @__PURE__ */ new Date()).getTimezoneOffset(), e = t > 0 ? "-" : "+", n = Math.abs(t), s = Math.floor(n / 60), o = n % 60;
102
+ return `${e}${s.toString().padStart(2, "0")}:${o.toString().padStart(2, "0")}`;
76
103
  } catch {
77
104
  return "+00:00";
78
105
  }
79
- }, D = () => {
106
+ }, C = () => {
80
107
  try {
81
- const t = /* @__PURE__ */ new Date(), e = I(), n = t.getFullYear(), o = (t.getMonth() + 1).toString().padStart(2, "0"), s = t.getDate().toString().padStart(2, "0"), c = t.getHours().toString().padStart(2, "0"), i = t.getMinutes().toString().padStart(2, "0"), g = t.getSeconds().toString().padStart(2, "0");
82
- return `${n}-${o}-${s}T${c}:${i}:${g}${e}`;
108
+ const t = /* @__PURE__ */ new Date(), e = E(), n = t.getFullYear(), s = (t.getMonth() + 1).toString().padStart(2, "0"), o = t.getDate().toString().padStart(2, "0"), r = t.getHours().toString().padStart(2, "0"), a = t.getMinutes().toString().padStart(2, "0"), c = t.getSeconds().toString().padStart(2, "0");
109
+ return `${n}-${s}-${o}T${r}:${a}:${c}${e}`;
83
110
  } catch {
84
111
  return (/* @__PURE__ */ new Date()).toISOString();
85
112
  }
86
- }, $ = (t, e = typeof window < "u" ? window.location : {}) => {
87
- const n = D(), o = w(), { properties: s } = t, { utm: c } = s, i = {
88
- url: s.url ?? e.href,
89
- doc_encoding: o.doc_encoding,
90
- doc_hash: s.hash ?? e.hash ?? "",
113
+ }, A = (t, e = typeof window < "u" ? window.location : {}) => {
114
+ const n = C(), s = S(), { properties: o } = t, r = {};
115
+ Object.keys(o).forEach((i) => {
116
+ f.includes(i) || (r[i] = o[i]);
117
+ });
118
+ const a = {
119
+ url: e.href,
120
+ doc_encoding: s.doc_encoding,
121
+ doc_hash: e.hash,
91
122
  doc_protocol: e.protocol,
92
- doc_search: s.search ?? e.search ?? "",
123
+ doc_search: e.search,
93
124
  doc_host: e.hostname,
94
- doc_path: s.path ?? e.pathname,
95
- title: s.title ?? (document == null ? void 0 : document.title),
96
- language_id: void 0,
97
- persona: void 0
98
- }, g = {
99
- screen_resolution: o.screen_resolution,
100
- language: o.user_language,
101
- viewport_width: String(s.width),
102
- viewport_height: String(s.height)
103
- }, a = {};
104
- if (c && typeof c == "object") {
105
- const r = c;
106
- r.medium && (a.medium = r.medium), r.source && (a.source = r.source), r.campaign && (a.campaign = r.campaign), r.term && (a.term = r.term), r.content && (a.content = r.content);
107
- }
125
+ doc_path: e.pathname,
126
+ title: o.title ?? (document == null ? void 0 : document.title)
127
+ }, c = y(e);
108
128
  return {
109
129
  ...t,
110
- page: i,
111
- device: g,
112
- ...Object.keys(a).length > 0 && { utm: a },
130
+ page: a,
131
+ ...Object.keys(c).length > 0 && { utm: c },
132
+ // Only include custom if there are user-provided properties
133
+ ...Object.keys(r).length > 0 && { custom: r },
113
134
  local_time: n
114
135
  };
115
136
  };
116
137
  export {
117
- $ as enrichPagePayloadOptimized,
118
- u as generateSecureId,
119
- T as getAnalyticsContext,
120
- D as getLocalTime,
121
- p as getSessionId,
122
- f as getUserId
138
+ A as enrichPagePayloadOptimized,
139
+ y as extractUTMParameters,
140
+ d as generateSecureId,
141
+ $ as getAnalyticsContext,
142
+ I as getDeviceDataForContext,
143
+ C as getLocalTime,
144
+ T as getSessionId,
145
+ p as getUserId,
146
+ U as validateAnalyticsConfig
123
147
  };
@@ -0,0 +1,103 @@
1
+ /**
2
+ * Data models for DotCMS Analytics
3
+ * Contains interfaces for data structures used in analytics events
4
+ */
5
+ /**
6
+ * Browser event data collected from the user's session in DotCMS.
7
+ * Contains comprehensive information about the user's browser environment,
8
+ * page context, and session details for analytics tracking.
9
+ *
10
+ * This is an internal type used by utility functions.
11
+ */
12
+ export interface DotCMSBrowserData {
13
+ /** UTC timestamp when the event occurred */
14
+ utc_time: string;
15
+ /** Local timezone offset in minutes */
16
+ local_tz_offset: number;
17
+ /** Screen resolution as a string (e.g., "1920x1080") */
18
+ screen_resolution: string;
19
+ /** Viewport size as a string (e.g., "1200x800") */
20
+ vp_size: string;
21
+ /** User's preferred language */
22
+ user_language: string;
23
+ /** Document encoding */
24
+ doc_encoding: string;
25
+ /** Document path */
26
+ doc_path: string;
27
+ /** Document host */
28
+ doc_host: string;
29
+ /** Document protocol (http/https) */
30
+ doc_protocol: string;
31
+ /** Document hash fragment */
32
+ doc_hash: string;
33
+ /** Document search parameters */
34
+ doc_search: string;
35
+ /** Referrer URL */
36
+ referrer: string;
37
+ /** Page title */
38
+ page_title: string;
39
+ /** Current page URL */
40
+ url: string;
41
+ /** UTM parameters for campaign tracking */
42
+ utm: DotCMSEventUtmData;
43
+ }
44
+ /**
45
+ * Analytics context shared across all events in DotCMS.
46
+ * Contains session and user identification data that provides
47
+ * continuity across multiple analytics events.
48
+ */
49
+ export interface DotCMSAnalyticsEventContext {
50
+ /** The site key for the DotCMS instance */
51
+ site_auth: string;
52
+ /** Unique session identifier */
53
+ session_id: string;
54
+ /** Unique user identifier */
55
+ user_id: string;
56
+ /** Device and browser information */
57
+ device: DotCMSEventDeviceData;
58
+ }
59
+ /**
60
+ * Device and browser information for DotCMS analytics tracking.
61
+ * Contains technical details about the user's device and browser environment.
62
+ */
63
+ export interface DotCMSEventDeviceData {
64
+ /** Screen resolution as a string (e.g., "1920x1080") */
65
+ screen_resolution: string;
66
+ /** User's preferred language */
67
+ language: string;
68
+ /** Viewport width in pixels */
69
+ viewport_width: string;
70
+ /** Viewport height in pixels */
71
+ viewport_height: string;
72
+ }
73
+ /**
74
+ * UTM (Urchin Tracking Module) parameters for DotCMS campaign tracking.
75
+ * Contains marketing campaign attribution data extracted from URL parameters.
76
+ */
77
+ export interface DotCMSEventUtmData {
78
+ /** The marketing medium (e.g., email, social, cpc) */
79
+ medium?: string;
80
+ /** The traffic source (e.g., google, newsletter) */
81
+ source?: string;
82
+ /** The campaign name */
83
+ campaign?: string;
84
+ /** The campaign term or keyword */
85
+ term?: string;
86
+ /** The campaign content or ad variation */
87
+ content?: string;
88
+ /** The campaign ID for tracking specific campaigns */
89
+ id?: string;
90
+ }
91
+ /**
92
+ * Page data structure for DotCMS analytics.
93
+ * Contains comprehensive information about the current page and its context
94
+ * within the DotCMS environment.
95
+ */
96
+ export type DotCMSEventPageData = Pick<DotCMSBrowserData, 'url' | 'doc_path' | 'doc_hash' | 'doc_search' | 'doc_host' | 'doc_protocol' | 'doc_encoding'> & {
97
+ /** Page title */
98
+ title: string | undefined;
99
+ /** Language identifier */
100
+ language_id?: string;
101
+ /** Persona identifier */
102
+ persona?: string;
103
+ };
@@ -0,0 +1,64 @@
1
+ import { DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
2
+ import { DotCMSCustomEventType, DotCMSEventType, DotCMSPredefinedEventType } from '../constants/dot-content-analytics.constants';
3
+ /**
4
+ * JSON value type for analytics custom data.
5
+ * Represents any valid JSON value that can be serialized and sent to the analytics server.
6
+ */
7
+ export type JsonValue = string | number | boolean | null | undefined | JsonObject | JsonArray;
8
+ /**
9
+ * JSON object type for analytics custom data.
10
+ */
11
+ export type JsonObject = {
12
+ [key: string]: JsonValue;
13
+ };
14
+ /**
15
+ * JSON array type for analytics custom data.
16
+ */
17
+ export type JsonArray = JsonValue[];
18
+ /**
19
+ * Generic base event structure for DotCMS Analytics.
20
+ * All events share this base structure with customizable event type and data.
21
+ *
22
+ * @template TEventType - The type of the event (pageview, custom event name, etc.)
23
+ * @template TData - The data structure for the event
24
+ */
25
+ export interface DotCMSEventBase<TEventType extends DotCMSEventType, TData> {
26
+ /** The type of event being tracked */
27
+ event_type: TEventType;
28
+ /** Local timestamp when the event occurred */
29
+ local_time: string;
30
+ /** Event-specific data with structured format */
31
+ data: TData;
32
+ }
33
+ /**
34
+ * Data structure for pageview events.
35
+ * Contains page and optional UTM/custom data.
36
+ */
37
+ export type DotCMSPageViewEventData = {
38
+ /** Page data associated with the event */
39
+ page: DotCMSEventPageData;
40
+ /** UTM parameters for campaign tracking (optional) */
41
+ utm?: DotCMSEventUtmData;
42
+ /** Custom data associated with the event (any valid JSON) */
43
+ custom?: JsonObject;
44
+ };
45
+ /**
46
+ * Data structure for custom events.
47
+ * Contains user-defined custom data.
48
+ */
49
+ export type DotCMSCustomEventData = {
50
+ /** Custom data associated with the event (any valid JSON) */
51
+ custom: JsonObject;
52
+ };
53
+ /**
54
+ * Pageview event structure.
55
+ */
56
+ export type DotCMSPageViewEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.PAGEVIEW, DotCMSPageViewEventData>;
57
+ /**
58
+ * Custom event structure.
59
+ */
60
+ export type DotCMSCustomEvent = DotCMSEventBase<DotCMSCustomEventType, DotCMSCustomEventData>;
61
+ /**
62
+ * Union type for all possible analytics events.
63
+ */
64
+ export type DotCMSEvent = DotCMSPageViewEvent | DotCMSCustomEvent;
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Central export point for all DotCMS Analytics models
3
+ */
4
+ export * from './data.model';
5
+ export * from './event.model';
6
+ export * from './request.model';
7
+ export * from './library.model';