@dotcms/analytics 26.9.18-1 → 26.9.18-1-next.2741

package/MIGRATION.md

@@ -0,0 +1,42 @@
+# Migration guide
+
+## The package root is now framework-neutral
+
+**Affects:** anyone importing React APIs from `@dotcms/analytics` directly.
+
+Previously `@dotcms/analytics` and `@dotcms/analytics/react` resolved to exactly the same module — the package root was a single re-export of the React bindings:
+
+```ts
+// src/index.ts, before
+export * from './lib/react';
+```
+
+That meant importing the package at all pulled in `react`, `next/navigation` and `@dotcms/uve`, even for a consumer that only wanted to initialize tracking. It also left the framework-neutral analytics engine — `initializeContentAnalytics`, the plugins, the queue and the trackers — with no entrypoint of its own.
+
+The root now exports only the framework-neutral API. The React bindings stay exactly where they already were, behind the explicit `./react` subpath.
+
+### What to change
+
+If you import `useContentAnalytics` or `DotContentAnalytics` from the package root, add `/react` to the specifier:
+
+```diff
+- import { useContentAnalytics, DotContentAnalytics } from '@dotcms/analytics';
++ import { useContentAnalytics, DotContentAnalytics } from '@dotcms/analytics/react';
+```
+
+Nothing else changes: the components, hooks and their signatures are untouched, and `@dotcms/analytics/react` already worked before this release, so you can make the change ahead of upgrading.
+
+### What you get for it
+
+A non-React consumer can now use analytics without React in the bundle at all:
+
+```ts
+import { initializeContentAnalytics } from '@dotcms/analytics';
+
+const analytics = initializeContentAnalytics({ siteAuth: '…', server: '…' });
+analytics?.pageView();
+```
+
+### Also in this release
+
+`next` is now declared as an optional peer dependency. The `./react` entry has always imported `next/navigation` (through `useRouterTracker`), but never said so, which left package managers unable to warn about a missing or mismatched Next.js version. It is marked optional because the neutral root does not need it.

package/README.md

@@ -1,6 +1,15 @@
 # @dotcms/analytics
 
-Content Analytics SDK for tracking content-aware events in dotCMS-powered React applications.
+Content Analytics SDK for tracking content-aware events in dotCMS-powered applications.
+
+## Entrypoints
+
+| Import | Contains | Use it when |
+| --- | --- | --- |
+| `@dotcms/analytics` | The framework-neutral engine: `initializeContentAnalytics`, `getAnalyticsConfig`, and the shared types. No React, no Next.js. | You are not using React, or you want to drive analytics yourself. |
+| `@dotcms/analytics/react` | `DotContentAnalytics` and `useContentAnalytics`, including the Next.js App Router integration. | You are using React. This is what the rest of this guide uses. |
+
+> **Upgrading?** The package root used to re-export the React bindings, so `@dotcms/analytics` and `@dotcms/analytics/react` resolved to the same module. The root is now framework-neutral. If you imported `useContentAnalytics` or `DotContentAnalytics` from the root, add `/react` to the specifier — see [MIGRATION.md](./MIGRATION.md).
 
 ## Which SDK Version Should I Use?
 

package/index.d.ts

@@ -1 +1 @@
-export * from './lib/react';
+export * from './lib/core/public-api';

package/index.js

@@ -1,6 +1,6 @@
-import { DotContentAnalytics as n } from "./lib/react/components/DotContentAnalytics.js";
-import { useContentAnalytics as r } from "./lib/react/hook/useContentAnalytics.js";
+import { getAnalyticsConfig as n } from "./lib/core/shared/utils/dot-analytics.utils.js";
+import { initializeContentAnalytics as e } from "./lib/core/dot-analytics.content.js";
 export {
-  n as DotContentAnalytics,
-  r as useContentAnalytics
+  n as getAnalyticsConfig,
+  e as initializeContentAnalytics
 };

package/lib/core/dot-analytics.content.js

@@ -1,15 +1,14 @@
 import { Analytics as l } from "analytics";
 import { getUVEState as d } from "../../uve/src/lib/core/core.utils.js";
-import "../../uve/src/internal/constants.js";
 import { dotAnalyticsClickPlugin as y } from "./plugin/click/dot-analytics.click.plugin.js";
-import { dotAnalyticsEnricherPlugin as m } from "./plugin/enricher/dot-analytics.enricher.plugin.js";
-import { dotAnalyticsIdentityPlugin as u } from "./plugin/identity/dot-analytics.identity.plugin.js";
+import { dotAnalyticsEnricherPlugin as u } from "./plugin/enricher/dot-analytics.enricher.plugin.js";
+import { dotAnalyticsIdentityPlugin as m } from "./plugin/identity/dot-analytics.identity.plugin.js";
 import { dotAnalyticsImpressionPlugin as A } from "./plugin/impression/dot-analytics.impression.plugin.js";
-import { dotAnalytics as p } from "./plugin/main/dot-analytics.plugin.js";
-import { ANALYTICS_WINDOWS_ACTIVE_KEY as e, ANALYTICS_WINDOWS_CLEANUP_KEY as f, DotCMSPredefinedEventType as w } from "./shared/constants/dot-analytics.constants.js";
+import { dotAnalytics as f } from "./plugin/main/dot-analytics.plugin.js";
+import { ANALYTICS_WINDOWS_ACTIVE_KEY as e, ANALYTICS_WINDOWS_CLEANUP_KEY as p, DotCMSPredefinedEventType as w } from "./shared/constants/dot-analytics.constants.js";
 import { validateAnalyticsConfig as C, isBrowser as g, getEnhancedTrackingPlugins as E } from "./shared/utils/dot-analytics.utils.js";
 import { cleanupActivityTracking as S } from "./plugin/identity/dot-analytics.identity.activity-tracker.js";
-const O = (t) => {
+const h = (t) => {
   const r = C(t);
   if (r)
     return console.error(
@@ -25,17 +24,17 @@ const O = (t) => {
     app: "dotAnalytics",
     debug: t.debug,
     plugins: [
-      u(t),
+      m(t),
       // Inject identity context
       ...s,
       //Track content impressions & clicks (conditionally loaded)
-      m(),
+      u(),
       // Enrich and clean payload with page, device, utm data and custom data
-      p(t)
+      f(t)
       // Send events to server
     ]
   }), a = () => S();
-  return typeof window < "u" && (window.addEventListener("beforeunload", a), window[f] = a, window[e] = !0, window.dispatchEvent(new CustomEvent("dotcms:analytics:ready"))), {
+  return typeof window < "u" && (window.addEventListener("beforeunload", a), window[p] = a, window[e] = !0, window.dispatchEvent(new CustomEvent("dotcms:analytics:ready"))), {
     /**
      * Track a page view.
      * Session activity is automatically updated by the identity plugin.
@@ -83,5 +82,5 @@ const O = (t) => {
   };
 };
 export {
-  O as initializeContentAnalytics
+  h as initializeContentAnalytics
 };

package/lib/core/plugin/identity/dot-analytics.identity.plugin.d.ts

@@ -24,8 +24,8 @@ export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig)
      * This runs BEFORE the enricher plugin
      */
     pageStart: ({ payload }: AnalyticsBaseParams) => {
-        context: import('../../shared/models').DotCMSAnalyticsEventContext;
-        type: "page" | "track";
+        context: import('../../public-api').DotCMSAnalyticsEventContext;
+        type: "track" | "page";
         properties: Record<string, unknown>;
         options: Record<string, unknown>;
         userId: string;
@@ -41,8 +41,8 @@ export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig)
      * This runs BEFORE the enricher plugin
      */
     trackStart: ({ payload }: AnalyticsBaseParams) => {
-        context: import('../../shared/models').DotCMSAnalyticsEventContext;
-        type: "page" | "track";
+        context: import('../../public-api').DotCMSAnalyticsEventContext;
+        type: "track" | "page";
         properties: Record<string, unknown>;
         options: Record<string, unknown>;
         userId: string;

package/lib/core/plugin/impression/dot-analytics.impression-tracker.js

@@ -1,9 +1,9 @@
 import { getViewportMetrics as m, isElementMeetingVisibilityThreshold as d } from "./dot-analytics.impression.utils.js";
-import { DEFAULT_IMPRESSION_CONFIG as l, IMPRESSION_EVENT_TYPE as u } from "../../shared/constants/dot-analytics.constants.js";
-import { createPluginLogger as g, isBrowser as a, INITIAL_SCAN_DELAY_MS as p, findContentlets as b, extractContentletIdentifier as c, createContentletObserver as f, extractContentletData as v } from "../../shared/utils/dot-analytics.utils.js";
+import { createPluginLogger as u, isBrowser as l, INITIAL_SCAN_DELAY_MS as g, findContentlets as p, extractContentletIdentifier as a, createContentletObserver as b, extractContentletData as f } from "../../shared/utils/dot-analytics.utils.js";
+import { DEFAULT_IMPRESSION_CONFIG as c, IMPRESSION_EVENT_TYPE as v } from "../../shared/constants/dot-analytics.constants.js";
 class T {
   constructor(e) {
-    this.observer = null, this.mutationObserver = null, this.elementImpressionStates = /* @__PURE__ */ new Map(), this.sessionTrackedImpressions = /* @__PURE__ */ new Set(), this.currentPagePath = "", this.subscribers = /* @__PURE__ */ new Set(), this.logger = g("Impression", e), this.impressionConfig = this.resolveImpressionConfig(e.impressions);
+    this.observer = null, this.mutationObserver = null, this.elementImpressionStates = /* @__PURE__ */ new Map(), this.sessionTrackedImpressions = /* @__PURE__ */ new Set(), this.currentPagePath = "", this.subscribers = /* @__PURE__ */ new Set(), this.logger = u("Impression", e), this.impressionConfig = this.resolveImpressionConfig(e.impressions);
   }
   /**
    * Subscribe to impression events
@@ -29,16 +29,16 @@ class T {
   }
   /** Merges user config with defaults */
   resolveImpressionConfig(e) {
-    return typeof e != "object" || e === null ? { ...l } : {
-      ...l,
+    return typeof e != "object" || e === null ? { ...c } : {
+      ...c,
       ...e
     };
   }
   /** Initializes tracking: sets up observers, finds contentlets, handles visibility/navigation */
   initialize() {
-    a() && (this.initializeIntersectionObserver(), typeof window < "u" && setTimeout(() => {
+    l() && (this.initializeIntersectionObserver(), typeof window < "u" && setTimeout(() => {
       this.logger.debug("Running initial scan after timeout..."), this.findAndObserveContentletElements();
-    }, p), this.initializeDynamicContentDetector(), this.initializePageVisibilityHandler(), this.initializePageNavigationHandler(), this.logger.info("Impression tracking initialized with config:", this.impressionConfig));
+    }, g), this.initializeDynamicContentDetector(), this.initializePageVisibilityHandler(), this.initializePageNavigationHandler(), this.logger.info("Impression tracking initialized with config:", this.impressionConfig));
   }
   /** Sets up IntersectionObserver with configured visibility threshold */
   initializeIntersectionObserver() {
@@ -55,7 +55,7 @@ class T {
   /** Finds contentlets in DOM, validates them, and starts observing (respects maxNodes limit) */
   findAndObserveContentletElements() {
     if (!this.observer) return;
-    const e = b();
+    const e = p();
     if (e.length === 0) {
       this.logger.warn("No contentlets found to track");
       return;
@@ -63,7 +63,7 @@ class T {
     const i = Math.min(e.length, this.impressionConfig.maxNodes);
     let t = 0;
     for (let s = 0; s < i; s++) {
-      const n = e[s], r = c(n);
+      const n = e[s], r = a(n);
       if (r) {
         const o = this.shouldSkipElement(n);
         if (o) {
@@ -84,7 +84,7 @@ class T {
   }
   /** Watches for new contentlets added to DOM (debounced for performance) */
   initializeDynamicContentDetector() {
-    a() && (this.mutationObserver = f(() => {
+    l() && (this.mutationObserver = b(() => {
       this.findAndObserveContentletElements();
     }), this.logger.info("MutationObserver enabled for dynamic content detection"));
   }
@@ -118,7 +118,7 @@ class T {
   /** Handles visibility changes: starts timer on enter, cancels on exit */
   processIntersectionChanges(e) {
     document.visibilityState === "visible" && e.forEach((i) => {
-      const t = i.target, s = c(t);
+      const t = i.target, s = a(t);
       s && (i.isIntersecting ? this.startImpressionDwellTimer(s, t) : this.cancelImpressionDwellTimer(s));
     });
   }
@@ -142,7 +142,7 @@ class T {
   trackAndSendImpression(e, i) {
     const t = this.elementImpressionStates.get(e);
     if (!t) return;
-    const s = t.visibleSince ? Date.now() - t.visibleSince : 0, n = v(i), r = m(i), o = parseInt(i.dataset.dotDomIndex || "-1", 10), h = {
+    const s = t.visibleSince ? Date.now() - t.visibleSince : 0, n = f(i), r = m(i), o = parseInt(i.dataset.dotDomIndex || "-1", 10), h = {
       content: {
         identifier: n.identifier,
         inode: n.inode,
@@ -154,7 +154,7 @@ class T {
         dom_index: o
       }
     };
-    this.notifySubscribers(u, h), this.markImpressionAsTracked(e), t.timer = null, t.visibleSince = null, t.tracked = !0, this.observer && this.observer.unobserve(i), this.logger.info(
+    this.notifySubscribers(v, h), this.markImpressionAsTracked(e), t.timer = null, t.visibleSince = null, t.tracked = !0, this.observer && this.observer.unobserve(i), this.logger.info(
       `Fired impression for ${e} (dwell: ${s}ms) - element unobserved`,
       n
     );

package/lib/core/public-api.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Framework-neutral public API for `@dotcms/analytics`.
+ *
+ * This is the package root (`@dotcms/analytics`). It contains no React and no Next.js: the
+ * React bindings — `DotContentAnalytics` and `useContentAnalytics`, which depend on
+ * `react` and `next/navigation` — live behind the explicit `@dotcms/analytics/react`
+ * subpath so a Vue, Angular, Astro or plain-JS consumer never pulls them in.
+ */
+export { initializeContentAnalytics } from './dot-analytics.content';
+export { getAnalyticsConfig } from './shared/utils/dot-analytics.utils';
+export type { DotCMSAnalytics, DotCMSAnalyticsConfig, DotCMSAnalyticsParams, ContentletData, ImpressionConfig, QueueConfig } from './shared/models';
+export type { DotCMSAnalyticsEventContext, DotCMSEventPageData, DotCMSImpressionEventData } from './shared/models';

package/lib/core/shared/constants/dot-analytics.constants.js

@@ -1,4 +1,4 @@
-const c = "/api/v1/analytics/content/event", o = {
+const S = "/api/v1/analytics/content/event", c = {
   PAGEVIEW: "pageview",
   CONTENT_IMPRESSION: "content_impression",
   CONTENT_CLICK: "content_click",
@@ -9,12 +9,12 @@ const c = "/api/v1/analytics/content/event", o = {
   "utm_campaign",
   "utm_term",
   "utm_content"
-], I = 30, e = "dot_analytics_session_id", N = "dot_analytics_user_id", _ = 15, E = 5e3, A = ["click"], O = {
+], o = 30, e = "dot_analytics_session_id", N = "dot_analytics_user_id", _ = 15, E = 5e3, A = ["click"], L = {
   eventBatchSize: _,
   // Max events per batch - auto-sends when reached
   flushInterval: E
   // Time between flushes - sends whatever is queued
-}, L = [
+}, O = "ca.min.js", i = [
   "title",
   "url",
   "path",
@@ -23,36 +23,37 @@ const c = "/api/v1/analytics/content/event", o = {
   "width",
   "height",
   "referrer"
-], t = 0.5, n = 750, T = 100, S = 100, i = 250, C = {
+], t = 0.5, n = 750, T = 100, I = 100, C = 250, U = {
   visibilityThreshold: t,
   dwellMs: n,
   maxNodes: T,
-  throttleMs: S
-}, U = "content_impression", a = "content_click", D = 300, M = "a, button", R = "__dotAnalyticsActive__", l = "__dotAnalyticsCleanup__", F = "dotcms-contentlet", P = "dot_analytics_tab_id", d = "dot_analytics_queue", r = 1440 * 60 * 1e3;
+  throttleMs: I
+}, a = "content_impression", M = "content_click", D = 300, R = "a, button", l = "__dotAnalyticsActive__", F = "__dotAnalyticsCleanup__", P = "dotcms-contentlet", d = "dot_analytics_tab_id", r = "dot_analytics_queue", Y = 1440 * 60 * 1e3;
 export {
   A as ACTIVITY_EVENTS,
-  c as ANALYTICS_ENDPOINT,
-  L as ANALYTICS_JS_DEFAULT_PROPERTIES,
-  R as ANALYTICS_WINDOWS_ACTIVE_KEY,
-  l as ANALYTICS_WINDOWS_CLEANUP_KEY,
-  M as CLICKABLE_ELEMENTS_SELECTOR,
-  a as CLICK_EVENT_TYPE,
-  F as CONTENTLET_CLASS,
+  S as ANALYTICS_ENDPOINT,
+  i as ANALYTICS_JS_DEFAULT_PROPERTIES,
+  O as ANALYTICS_MINIFIED_SCRIPT_NAME,
+  l as ANALYTICS_WINDOWS_ACTIVE_KEY,
+  F as ANALYTICS_WINDOWS_CLEANUP_KEY,
+  R as CLICKABLE_ELEMENTS_SELECTOR,
+  M as CLICK_EVENT_TYPE,
+  P as CONTENTLET_CLASS,
   D as DEFAULT_CLICK_THROTTLE_MS,
-  C as DEFAULT_IMPRESSION_CONFIG,
+  U as DEFAULT_IMPRESSION_CONFIG,
   n as DEFAULT_IMPRESSION_DWELL_MS,
   T as DEFAULT_IMPRESSION_MAX_NODES,
-  i as DEFAULT_IMPRESSION_MUTATION_OBSERVER_DEBOUNCE_MS,
-  S as DEFAULT_IMPRESSION_THROTTLE_MS,
+  C as DEFAULT_IMPRESSION_MUTATION_OBSERVER_DEBOUNCE_MS,
+  I as DEFAULT_IMPRESSION_THROTTLE_MS,
   t as DEFAULT_IMPRESSION_VISIBILITY_THRESHOLD,
-  O as DEFAULT_QUEUE_CONFIG,
-  I as DEFAULT_SESSION_TIMEOUT_MINUTES,
-  o as DotCMSPredefinedEventType,
+  L as DEFAULT_QUEUE_CONFIG,
+  o as DEFAULT_SESSION_TIMEOUT_MINUTES,
+  c as DotCMSPredefinedEventType,
   s as EXPECTED_UTM_KEYS,
-  U as IMPRESSION_EVENT_TYPE,
-  r as MAX_EVENT_AGE_MS,
-  d as QUEUE_STORAGE_KEY_PREFIX,
+  a as IMPRESSION_EVENT_TYPE,
+  Y as MAX_EVENT_AGE_MS,
+  r as QUEUE_STORAGE_KEY_PREFIX,
   e as SESSION_STORAGE_KEY,
-  P as TAB_ID_STORAGE_KEY,
+  d as TAB_ID_STORAGE_KEY,
   N as USER_ID_KEY
 };

package/lib/core/shared/http/dot-analytics.http.js

@@ -1,7 +1,7 @@
-import { ANALYTICS_ENDPOINT as p } from "../constants/dot-analytics.constants.js";
-import { createPluginLogger as l } from "../utils/dot-analytics.utils.js";
+import { createPluginLogger as p } from "../utils/dot-analytics.utils.js";
+import { ANALYTICS_ENDPOINT as l } from "../constants/dot-analytics.constants.js";
 const m = async (n, i, c = !1) => {
-  const e = l("HTTP", i), f = `${i.server}${p}`, g = JSON.stringify(n);
+  const e = p("HTTP", i), f = `${i.server}${l}`, g = JSON.stringify(n);
   e.info(`Sending ${n.events.length} event(s)${c ? " (keepalive)" : ""}`, {
     payload: n
   });

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

@@ -1,15 +1,15 @@
 import q from "@analytics/queue-utils";
 import F from "@analytics/router-utils";
-import { DEFAULT_QUEUE_CONFIG as x, TAB_ID_STORAGE_KEY as I, MAX_EVENT_AGE_MS as z, QUEUE_STORAGE_KEY_PREFIX as P } from "../constants/dot-analytics.constants.js";
-import { sendAnalyticsEvent as w } from "../http/dot-analytics.http.js";
-import { createPluginLogger as T, safeSessionStorage as d, generateSecureId as U, getAnalyticsContext as D } from "../utils/dot-analytics.utils.js";
+import { sendAnalyticsEvent as I } from "../http/dot-analytics.http.js";
+import { createPluginLogger as x, safeSessionStorage as d, generateSecureId as z, getAnalyticsContext as P } from "../utils/dot-analytics.utils.js";
+import { DEFAULT_QUEUE_CONFIG as T, TAB_ID_STORAGE_KEY as w, MAX_EVENT_AGE_MS as U, QUEUE_STORAGE_KEY_PREFIX as D } from "../constants/dot-analytics.constants.js";
 const R = (l) => {
-  const n = T("Queue", l);
+  const n = x("Queue", l);
   let i = null, c = null, f = !1, m = !1, v = typeof window < "u" ? window.location.pathname : "", o = "", a = [];
   const y = {
-    ...x,
+    ...T,
     ...typeof l.queue == "object" ? l.queue : {}
-  }, g = () => `${P}_${o}`, E = (e) => {
+  }, g = () => `${D}_${o}`, E = (e) => {
     const t = e;
     if (!t || typeof t != "object" || Array.isArray(t))
       return null;
@@ -32,7 +32,7 @@ const R = (l) => {
       if (!r)
         return d.removeItem(e), null;
       const u = Date.now() - r.timestamp;
-      return u > z ? (n.warn(
+      return u > U ? (n.warn(
         `Persisted events too old (${Math.round(u / 1e3 / 60 / 60)}h), discarding`
       ), d.removeItem(e), null) : (n.info(
         `Loaded ${r.events.length} persisted event(s) from storage (age: ${Math.round(u / 1e3)}s)`
@@ -63,14 +63,14 @@ const R = (l) => {
     if (e.length === 0)
       return !0;
     n.info(`Sending ${e.length} persisted event(s) immediately`);
-    const r = { context: D(l), events: e };
-    return w(r, l, t);
+    const r = { context: P(l), events: e };
+    return I(r, l, t);
   }, $ = (e, t) => {
     if (!c) return;
     n.debug(`Sending batch of ${e.length} event(s)`, {
       events: e,
       keepalive: f
-    }), w({ context: c, events: e }, l, f), a = a.filter(
+    }), I({ context: c, events: e }, l, f), a = a.filter(
       (r) => !e.some((u) => u === r)
     ), a.length === 0 ? b() : h();
   }, p = () => {
@@ -90,13 +90,13 @@ const R = (l) => {
      */
     initialize: () => {
       if (typeof window < "u") {
-        const t = d.getItem(I);
+        const t = d.getItem(w);
         if (t)
           o = t, n.debug(`Reusing Tab ID: ${o}`);
         else {
-          typeof crypto < "u" && typeof crypto.randomUUID == "function" ? o = crypto.randomUUID() : (o = U("tab"), n.debug("crypto.randomUUID not available, using fallback generator"));
+          typeof crypto < "u" && typeof crypto.randomUUID == "function" ? o = crypto.randomUUID() : (o = z("tab"), n.debug("crypto.randomUUID not available, using fallback generator"));
           try {
-            d.setItem(I, o);
+            d.setItem(w, o);
           } catch {
           }
           n.debug(`Generated new Tab ID: ${o}`);