@dotcms/analytics 1.1.1 → 1.2.0-next.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/analytics",
-  "version": "1.1.1",
+  "version": "1.2.0-next.10",
   "description": "Official JavaScript library for Content Analytics with DotCMS.",
   "repository": {
     "type": "git",
@@ -20,19 +20,21 @@
   },
   "homepage": "https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/analytics/README.md",
   "dependencies": {
-    "analytics": "^0.8.0",
     "@analytics/core": "^0.13.0",
+    "@analytics/queue-utils": "^0.1.3",
+    "@analytics/router-utils": "^0.1.1",
     "@analytics/storage-utils": "^0.4.0",
-    "@dotcms/uve": "latest"
+    "@dotcms/uve": "latest",
+    "analytics": "^0.8.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19"
   },
   "devDependencies": {
+    "@dotcms/types": "latest",
     "@testing-library/jest-dom": "^6.1.6",
     "@testing-library/react": "^14.0.0",
-    "vite": "~5.0.0",
-    "@dotcms/types": "latest"
+    "vite": "~5.0.0"
   },
   "main": "./index.js",
   "module": "./index.js",

package/uve/src/internal/constants.js

@@ -1,3 +1,8 @@
-import { UVEEventType as n } from "../../../types/src/lib/editor/public.js";
-import { onContentletHovered as r, onIframeScroll as o, onRequestBounds as t, onPageReload as E, onContentChanges as u } from "./events.js";
-n.CONTENT_CHANGES + "", n.PAGE_RELOAD + "", n.REQUEST_BOUNDS + "", n.IFRAME_SCROLL + "", n.CONTENTLET_HOVERED + "";
+import { UVEEventType as t } from "../../../types/src/lib/editor/public.js";
+import { onContentletHovered as e, onIframeScroll as o, onRequestBounds as r, onPageReload as E, onContentChanges as _ } from "./events.js";
+t.CONTENT_CHANGES + "", t.PAGE_RELOAD + "", t.REQUEST_BOUNDS + "", t.IFRAME_SCROLL + "", t.CONTENTLET_HOVERED + "";
+const N = "__dotAnalyticsActive__", T = "__dotAnalyticsCleanup";
+export {
+  N as ANALYTICS_WINDOWS_ACTIVE_KEY,
+  T as ANALYTICS_WINDOWS_CLEANUP_KEY
+};

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

@@ -1,43 +0,0 @@
-import { Analytics as s } from "analytics";
-import { dotAnalytics as l } from "./plugin/dot-analytics.plugin.js";
-import { dotAnalyticsEnricherPlugin as a } from "./plugin/enricher/dot-analytics.enricher.plugin.js";
-import { dotAnalyticsIdentityPlugin as u } from "./plugin/identity/dot-analytics.identity.plugin.js";
-import { cleanupActivityTracking as c, updateSessionActivity as o } from "./shared/dot-content-analytics.activity-tracker.js";
-const f = (n) => {
-  if (!n.siteKey)
-    return console.error('DotContentAnalytics: Missing "siteKey" in configuration'), null;
-  if (!n.server)
-    return console.error('DotContentAnalytics: Missing "server" in configuration'), null;
-  const t = s({
-    app: "dotAnalytics",
-    debug: n.debug,
-    plugins: [
-      u(n),
-      // Inject identity context (user_id, session_id, local_tz)
-      a(),
-      // Enrich with page, device, utm data
-      l(n)
-      // Send events to server
-    ]
-  }), e = () => c();
-  return typeof window < "u" && (window.addEventListener("beforeunload", e), window.__dotAnalyticsCleanup = e), {
-    /**
-     * Track a page view.
-     * @param {Record<string, unknown>} payload - The payload to track.
-     */
-    pageView: (i = {}) => {
-      o(), t == null || t.page(i);
-    },
-    /**
-     * Track a custom event.
-     * @param {string} eventName - The name of the event to track.
-     * @param {Record<string, unknown>} payload - The payload to track.
-     */
-    track: (i, r = {}) => {
-      o(), t == null || t.track(i, r);
-    }
-  };
-};
-export {
-  f as initializeContentAnalytics
-};

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

@@ -1,32 +0,0 @@
-import { DotCMSAnalyticsConfig, DotCMSAnalyticsParams } from '../shared/dot-content-analytics.model';
-/**
- * Analytics plugin for tracking page views and custom events in DotCMS applications.
- * This plugin handles sending analytics data to the DotCMS server, managing initialization,
- * and processing both automatic and manual tracking events.
- *
- * @param {DotCMSAnalyticsConfig} config - Configuration object containing API key, server URL,
- *                                     debug mode and auto page view settings
- * @returns {Object} Plugin object with methods for initialization and event tracking
- */
-export declare const dotAnalytics: (config: DotCMSAnalyticsConfig) => {
-    name: string;
-    config: DotCMSAnalyticsConfig;
-    /**
-     * Initialize the plugin
-     */
-    initialize: () => Promise<void>;
-    /**
-     * Track a page view event
-     * Takes enriched data from properties and creates final structured event
-     */
-    page: (params: DotCMSAnalyticsParams) => Promise<void>;
-    /**
-     * Track a custom event
-     * Takes enriched data and sends it to the analytics server
-     */
-    track: (params: DotCMSAnalyticsParams) => Promise<void>;
-    /**
-     * Check if the plugin is loaded
-     */
-    loaded: () => boolean;
-};

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

@@ -1,79 +0,0 @@
-import { EVENT_TYPES as y } from "../shared/dot-content-analytics.constants.js";
-import { sendAnalyticsEventToServer as c } from "../shared/dot-content-analytics.http.js";
-const p = (v) => {
-  let r = !1;
-  return {
-    name: "dot-analytics",
-    config: v,
-    /**
-     * Initialize the plugin
-     */
-    initialize: () => (r = !0, Promise.resolve()),
-    /**
-     * Track a page view event
-     * Takes enriched data from properties and creates final structured event
-     */
-    page: (a) => {
-      const { config: t, payload: e } = a, { context: n, page: o, device: i, utm: s, local_time: l } = e;
-      if (!r)
-        throw new Error("DotAnalytics: Plugin not initialized");
-      if (!n || !o || !i || !l)
-        throw new Error("DotAnalytics: Missing required payload data for pageview event");
-      const d = {
-        context: n,
-        events: [
-          {
-            event_type: y.PAGEVIEW,
-            local_time: l,
-            data: {
-              page: o,
-              device: i,
-              ...s && { utm: s }
-            }
-          }
-        ]
-      };
-      return t.debug && console.warn("DotAnalytics: Pageview event to send:", d), c(d, t);
-    },
-    // TODO: Fix this when we haver the final design for the track event
-    /**
-     * Track a custom event
-     * Takes enriched data and sends it to the analytics server
-     */
-    track: (a) => {
-      const { config: t, payload: e } = a;
-      if (!r)
-        throw new Error("DotAnalytics: Plugin not initialized");
-      if ("events" in e && Array.isArray(e.events)) {
-        const o = e, i = {
-          context: o.context,
-          events: o.events
-        };
-        return t.debug && console.warn("DotAnalytics: Track event to send:", i), c(i, t);
-      }
-      if (!e.context || !e.local_time)
-        throw new Error("DotAnalytics: Missing required payload data for track event");
-      const n = {
-        context: e.context,
-        events: [
-          {
-            event_type: y.TRACK,
-            local_time: e.local_time,
-            data: {
-              event: e.event,
-              ...e.properties
-            }
-          }
-        ]
-      };
-      return t.debug && console.warn("DotAnalytics: Track event to send (fallback):", n), c(n, t);
-    },
-    /**
-     * Check if the plugin is loaded
-     */
-    loaded: () => r
-  };
-};
-export {
-  p as dotAnalytics
-};

package/lib/core/shared/dot-content-analytics.activity-tracker.d.ts

@@ -1,28 +0,0 @@
-import { DotCMSAnalyticsConfig } from './dot-content-analytics.model';
-/**
- * Updates session activity with throttling
- */
-export declare const updateSessionActivity: () => void;
-/**
- * Gets session information for debugging
- */
-export declare const getSessionInfo: () => {
-    lastActivity: number;
-    isActive: boolean;
-};
-/**
- * Initializes activity tracking
- */
-export declare const initializeActivityTracking: (config: DotCMSAnalyticsConfig) => void;
-/**
- * Cleans up activity tracking listeners
- */
-export declare const cleanupActivityTracking: () => void;
-/**
- * Checks if user has been inactive
- */
-export declare const isUserInactive: () => boolean;
-/**
- * Gets last activity time
- */
-export declare const getLastActivity: () => number;

package/lib/core/shared/dot-content-analytics.constants.d.ts

@@ -1,37 +0,0 @@
-export declare const ANALYTICS_WINDOWS_KEY = "dotAnalytics";
-export declare const ANALYTICS_SOURCE_TYPE = "dotAnalytics";
-export declare const ANALYTICS_ENDPOINT = "/api/v1/analytics/content/event";
-/**
- * Event Types
- * Only two event types are supported in DotCMS Analytics
- */
-export declare const EVENT_TYPES: {
-    readonly PAGEVIEW: "pageview";
-    readonly TRACK: "track";
-};
-/**
- * Expected UTM parameter keys for campaign tracking
- */
-export declare const EXPECTED_UTM_KEYS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "utm_id"];
-/**
- * Session configuration constants
- */
-export declare const DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
-export declare const SESSION_STORAGE_KEY = "dot_analytics_session_id";
-export declare const SESSION_START_KEY = "dot_analytics_session_start";
-export declare const SESSION_UTM_KEY = "dot_analytics_session_utm";
-/**
- * User ID configuration constants
- */
-export declare const USER_ID_KEY = "dot_analytics_user_id";
-/**
- * Activity tracking configuration
- * Events used to detect user activity for session management
- * - click: Detects real user interaction with minimal performance impact
- * - visibilitychange: Handled separately to detect tab changes
- */
-export declare const ACTIVITY_EVENTS: readonly ["click"];
-/**
- * The name of the analytics minified script.
- */
-export declare const ANALYTICS_MINIFIED_SCRIPT_NAME = "ca.min.js";

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

@@ -1,14 +0,0 @@
-const t = "dotAnalytics", E = t, _ = "/api/v1/analytics/content/event", c = {
-  PAGEVIEW: "pageview",
-  TRACK: "track"
-}, n = 30, s = "dot_analytics_session_id", S = "dot_analytics_user_id", T = ["click"];
-export {
-  T as ACTIVITY_EVENTS,
-  _ as ANALYTICS_ENDPOINT,
-  E as ANALYTICS_SOURCE_TYPE,
-  t as ANALYTICS_WINDOWS_KEY,
-  n as DEFAULT_SESSION_TIMEOUT_MINUTES,
-  c as EVENT_TYPES,
-  s as SESSION_STORAGE_KEY,
-  S as USER_ID_KEY
-};

package/lib/core/shared/dot-content-analytics.http.d.ts

@@ -1,8 +0,0 @@
-import { DotCMSAnalyticsConfig, DotCMSAnalyticsRequestBody } from './dot-content-analytics.model';
-/**
- * Send an analytics event to the server
- * @param payload - The event payload data
- * @param config - The analytics configuration
- * @returns A promise that resolves when the request is complete
- */
-export declare const sendAnalyticsEventToServer: (payload: DotCMSAnalyticsRequestBody, config: DotCMSAnalyticsConfig) => Promise<void>;

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

@@ -1,29 +0,0 @@
-import { ANALYTICS_ENDPOINT as a } from "./dot-content-analytics.constants.js";
-const i = async (o, t) => {
-  try {
-    const e = await fetch(`${t.server}${a}`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(o)
-    });
-    if (!e.ok) {
-      const n = e.statusText || "Unknown Error", s = `HTTP ${e.status}: ${n}`;
-      try {
-        const r = await e.json();
-        r.message ? console.warn(`DotAnalytics: ${r.message} (${s})`) : console.warn(
-          `DotAnalytics: ${s} - No error message in response`
-        );
-      } catch (r) {
-        console.warn(
-          `DotAnalytics: ${s} - Failed to parse error response:`,
-          r
-        );
-      }
-    }
-  } catch (e) {
-    console.error("DotAnalytics: Error sending event:", e);
-  }
-};
-export {
-  i as sendAnalyticsEventToServer
-};

package/lib/core/shared/dot-content-analytics.model.d.ts

@@ -1,351 +0,0 @@
-import { EVENT_TYPES } from './dot-content-analytics.constants';
-declare global {
-    interface Window {
-        __dotAnalyticsCleanup?: () => void;
-    }
-}
-/**
- * Configuration interface for DotCMS Analytics SDK.
- * Contains all necessary settings for initializing and configuring the analytics client.
- */
-export interface DotCMSAnalyticsConfig {
-    /**
-     * The URL of the Analytics server endpoint.
-     */
-    server: string;
-    /**
-     * Enable debug mode to get additional logging information.
-     */
-    debug: boolean;
-    /**
-     * Automatically track page views when set to true.
-     */
-    autoPageView?: boolean;
-    /**
-     * The site key for authenticating with the Analytics service.
-     */
-    siteKey: string;
-}
-/**
- * Supported event types in DotCMS Analytics.
- * Only two event types are supported: pageview and track.
- */
-export type DotCMSEventType = (typeof EVENT_TYPES)[keyof typeof EVENT_TYPES];
-/**
- * Base structure for all analytics events.
- * All events share this common structure.
- */
-export interface DotCMSEventBase {
-    /** The type of event being tracked */
-    event_type: DotCMSEventType;
-    /** Local timestamp when the event occurred */
-    local_time: string;
-}
-/**
- * Pageview-specific analytics event structure.
- * Contains data specific to page view tracking.
- */
-export interface DotCMSPageViewEvent extends DotCMSEventBase {
-    event_type: 'pageview';
-    /** Pageview-specific event data with structured format */
-    data: {
-        /** Page data associated with the event */
-        page: DotCMSPageData;
-        /** Device and browser information */
-        device: DotCMSDeviceData;
-        /** UTM parameters for campaign tracking (optional) */
-        utm?: DotCMSUtmData;
-    };
-}
-/**
- * Track-specific analytics event structure.
- * Contains data specific to custom event tracking.
- */
-export interface DotCMSTrackEvent extends DotCMSEventBase {
-    event_type: 'track';
-    /** Track-specific event data with flexible structure */
-    data: Record<string, unknown>;
-}
-/**
- * Union type for all possible analytics events.
- */
-export type DotCMSEvent = DotCMSPageViewEvent | DotCMSTrackEvent;
-/**
- * Analytics request body for page view events in DotCMS.
- * Structure sent to the DotCMS analytics server for page tracking.
- */
-export interface DotCMSPageViewRequestBody {
-    /** Context information shared across all events */
-    context: DotCMSAnalyticsContext;
-    /** Array of pageview analytics events to be tracked */
-    events: DotCMSPageViewEvent[];
-}
-/**
- * Analytics request body for track events in DotCMS.
- * Structure sent to the DotCMS analytics server for custom event tracking.
- */
-export interface DotCMSTrackRequestBody {
-    /** Context information shared across all events */
-    context: DotCMSAnalyticsContext;
-    /** Array of track analytics events to be tracked */
-    events: DotCMSTrackEvent[];
-}
-/**
- * Union type for all possible request bodies.
- */
-export type DotCMSAnalyticsRequestBody = DotCMSPageViewRequestBody | DotCMSTrackRequestBody;
-/**
- * Enriched payload structure returned by the enricher plugin.
- * Contains pre-structured events and context for direct use in analytics requests.
- */
-export interface DotCMSEnrichedPayload {
-    /** Analytics context shared across events */
-    context: DotCMSAnalyticsContext;
-    /** Array of pre-structured analytics events */
-    events: DotCMSEvent[];
-}
-/**
- * Browser event data collected from the user's session in DotCMS.
- * Contains comprehensive information about the user's browser environment,
- * page context, and session details for analytics tracking.
- */
-export interface DotCMSBrowserEventData {
-    /** UTC timestamp when the event occurred */
-    utc_time: string;
-    /** Local timezone offset in minutes */
-    local_tz_offset: number;
-    /** Screen resolution as a string (e.g., "1920x1080") */
-    screen_resolution: string | undefined;
-    /** Viewport size as a string (e.g., "1200x800") */
-    vp_size: string | undefined;
-    /** User's preferred language */
-    user_language: string | undefined;
-    /** Document encoding */
-    doc_encoding: string | undefined;
-    /** Document path */
-    doc_path: string | undefined;
-    /** Document host */
-    doc_host: string | undefined;
-    /** Document protocol (http/https) */
-    doc_protocol: string | undefined;
-    /** Document hash fragment */
-    doc_hash: string;
-    /** Document search parameters */
-    doc_search: string;
-    /** Referrer URL */
-    referrer: string | undefined;
-    /** Page title */
-    page_title: string | undefined;
-    /** Current page URL */
-    url: string | undefined;
-    /** UTM parameters for campaign tracking */
-    utm: Record<string, string>;
-}
-/**
- * The payload structure for DotCMS analytics events.
- * This interface represents the complete data structure that flows through
- * the analytics pipeline, including original event data and enriched context.
- *
- * This is the internal payload used by Analytics.js and our plugins.
- */
-export interface DotCMSAnalyticsPayload {
-    /** The event name or identifier */
-    event: string;
-    /** Additional properties associated with the event */
-    properties: Record<string, unknown>;
-    /** Configuration options for the event */
-    options: Record<string, unknown>;
-    /** Analytics context shared across events */
-    context?: DotCMSAnalyticsContext;
-    /** Page data for the current page */
-    page?: DotCMSPageData;
-    /** Device and browser information */
-    device?: DotCMSDeviceData;
-    /** UTM parameters for campaign tracking */
-    utm?: DotCMSUtmData;
-    /** Local timestamp when the event occurred */
-    local_time: string;
-}
-/**
- * Parameters passed to DotCMS Analytics plugin methods.
- * Contains the configuration and payload data needed for processing analytics events.
- */
-export interface DotCMSAnalyticsParams {
-    /** Configuration for the analytics client */
-    config: DotCMSAnalyticsConfig;
-    /** The event payload to be processed */
-    payload: DotCMSAnalyticsPayload;
-}
-/**
- * Main interface for the DotCMS Analytics SDK.
- * Provides the core methods for tracking page views and custom events.
- */
-export interface DotCMSAnalytics {
-    /**
-     * Track a page view event.
-     */
-    pageView: () => void;
-    /**
-     * Track a custom event.
-     * @param eventName - The name/type of the event to track
-     * @param payload - Optional additional data to include with the event
-     */
-    track: (eventName: string, payload?: Record<string, unknown>) => void;
-}
-/**
- * Analytics context shared across all events in DotCMS.
- * Contains session and user identification data that provides
- * continuity across multiple analytics events.
- */
-export interface DotCMSAnalyticsContext {
-    /** The site key for the DotCMS instance */
-    site_key: string;
-    /** Unique session identifier */
-    session_id: string;
-    /** Unique user identifier */
-    user_id: string;
-}
-/**
- * Device and browser information for DotCMS analytics tracking.
- * Contains technical details about the user's device and browser environment.
- */
-export interface DotCMSDeviceData {
-    /** Screen resolution as a string (e.g., "1920x1080") */
-    screen_resolution: string | undefined;
-    /** User's preferred language */
-    language: string | undefined;
-    /** Viewport width in pixels */
-    viewport_width: string | undefined;
-    /** Viewport height in pixels */
-    viewport_height: string | undefined;
-}
-/**
- * UTM (Urchin Tracking Module) parameters for DotCMS campaign tracking.
- * Contains marketing campaign attribution data extracted from URL parameters.
- */
-export interface DotCMSUtmData {
-    /** The marketing medium (e.g., email, social, cpc) */
-    medium?: string;
-    /** The traffic source (e.g., google, newsletter) */
-    source?: string;
-    /** The campaign name */
-    campaign?: string;
-    /** The campaign term or keyword */
-    term?: string;
-    /** The campaign content or ad variation */
-    content?: string;
-    /** The campaign ID for tracking specific campaigns */
-    id?: string;
-}
-/**
- * Page data structure for DotCMS analytics.
- * Contains comprehensive information about the current page and its context
- * within the DotCMS environment.
- */
-export interface DotCMSPageData {
-    /** The current page URL */
-    url: string | undefined;
-    /** Document encoding */
-    doc_encoding: string | undefined;
-    /** Document hash fragment */
-    doc_hash: string;
-    /** Document protocol (http/https) */
-    doc_protocol: string | undefined;
-    /** Document search parameters */
-    doc_search: string;
-    /** Document host domain */
-    doc_host: string | undefined;
-    /** Document path */
-    doc_path: string | undefined;
-    /** Page title */
-    title: string | undefined;
-    /** Language identifier */
-    language_id?: string;
-    /** Persona identifier */
-    persona?: string;
-}
-/**
- * Analytics.js hook parameter types for DotCMS.
- * Represents the payload structure used by Analytics.js lifecycle hooks
- * for intercepting and modifying analytics events.
- */
-export interface DotCMSAnalyticsHookPayload {
-    /** The type of analytics event */
-    type: string;
-    /** Properties associated with the event */
-    properties: {
-        /** Page title */
-        title: string;
-        /** Page URL */
-        url: string;
-        /** Page path */
-        path: string;
-        /** URL hash fragment */
-        hash: string;
-        /** URL search parameters */
-        search: string;
-        /** Viewport width */
-        width: number;
-        /** Viewport height */
-        height: number;
-        /** Referrer URL */
-        referrer?: string;
-    };
-    /** Configuration options for the event */
-    options: Record<string, unknown>;
-    /** User identifier */
-    userId: string | null;
-    /** Anonymous user identifier */
-    anonymousId: string;
-    /** Metadata about the event */
-    meta: {
-        /** Request identifier */
-        rid: string;
-        /** Timestamp */
-        ts: number;
-        /** Whether the event has a callback function */
-        hasCallback: boolean;
-    };
-}
-/**
- * Analytics.js instance structure for DotCMS.
- * Represents the internal structure of an Analytics.js instance,
- * providing access to plugins, storage, and event configuration.
- */
-export interface DotCMSAnalyticsInstance {
-    /** Available plugins and their configurations */
-    plugins: Record<string, unknown>;
-    /** Storage mechanisms for analytics data */
-    storage: Record<string, unknown>;
-    /** Event configuration */
-    events: {
-        /** Core event types */
-        core: string[];
-        /** Plugin-specific event types */
-        plugins: string[];
-    };
-}
-/**
- * Parameters passed to Analytics.js hook functions in DotCMS.
- * Contains all the context and data needed for Analytics.js lifecycle hooks
- * to process and modify analytics events.
- */
-export interface DotCMSAnalyticsHookParams {
-    /** The event payload data */
-    payload: DotCMSAnalyticsHookPayload;
-    /** The analytics instance */
-    instance: DotCMSAnalyticsInstance;
-    /** Global configuration settings */
-    config: Record<string, unknown>;
-    /** Available plugins and their status */
-    plugins: Record<string, {
-        /** Whether the plugin is enabled */
-        enabled: boolean;
-        /** Whether the plugin is initialized */
-        initialized: boolean;
-        /** Whether the plugin is loaded */
-        loaded: boolean;
-        /** Plugin-specific configuration */
-        config: Record<string, unknown>;
-    }>;
-}