@dotcms/analytics 1.1.1-next.1 → 1.1.1-next.3

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

@@ -1,9 +1,9 @@
-import { SESSION_STORAGE_KEY as h, DEFAULT_SESSION_TIMEOUT_MINUTES as S, USER_ID_KEY as m } from "./dot-content-analytics.constants.js";
-let d = null;
-const u = (t) => {
-  const e = Date.now(), n = Math.random().toString(36).substr(2, 9), o = Math.random().toString(36).substr(2, 9);
-  return `${t}_${e}_${n}${o}`;
-}, l = {
+import { ANALYTICS_JS_DEFAULT_PROPERTIES as _, SESSION_STORAGE_KEY as S, DEFAULT_SESSION_TIMEOUT_MINUTES as f, USER_ID_KEY as l, EXPECTED_UTM_KEYS as w } from "./constants/dot-content-analytics.constants.js";
+let g = null, u = null;
+const d = (t) => {
+  const e = Date.now(), s = Math.random().toString(36).substr(2, 9), n = Math.random().toString(36).substr(2, 9);
+  return `${t}_${e}_${s}${n}`;
+}, m = {
   getItem: (t) => {
     try {
       return localStorage.getItem(t);
@@ -15,109 +15,122 @@ const u = (t) => {
     try {
       localStorage.setItem(t, e);
     } catch {
-      console.warn(`DotAnalytics: Could not save ${t} to localStorage`);
+      console.warn(`DotCMS Analytics: Could not save ${t} to localStorage`);
     }
   }
-}, f = () => {
-  let t = l.getItem(m);
-  return t || (t = u("user"), l.setItem(m, t)), t;
-}, _ = (t) => {
-  const e = new Date(t), n = /* @__PURE__ */ new Date(), o = new Date(
+}, p = () => {
+  let t = m.getItem(l);
+  return t || (t = d("user"), m.setItem(l, t)), t;
+}, T = (t) => {
+  const e = new Date(t), s = /* @__PURE__ */ new Date(), n = new Date(
     e.getUTCFullYear(),
     e.getUTCMonth(),
     e.getUTCDate()
-  ), s = new Date(n.getUTCFullYear(), n.getUTCMonth(), n.getUTCDate());
-  return o.getTime() !== s.getTime();
-}, p = () => {
+  ), o = new Date(s.getUTCFullYear(), s.getUTCMonth(), s.getUTCDate());
+  return n.getTime() !== o.getTime();
+}, D = () => {
   const t = Date.now();
   if (typeof window > "u")
-    return u("session_fallback");
+    return d("session_fallback");
   try {
-    const e = sessionStorage.getItem(h);
+    const e = sessionStorage.getItem(S);
     if (e) {
-      const { sessionId: s, startTime: c, lastActivity: i } = JSON.parse(e), g = !_(c), a = t - i < S * 60 * 1e3;
-      if (g && a)
+      const { sessionId: o, startTime: r, lastActivity: a } = JSON.parse(e), c = !T(r), i = t - a < f * 60 * 1e3;
+      if (c && i)
         return sessionStorage.setItem(
-          h,
+          S,
           JSON.stringify({
-            sessionId: s,
-            startTime: c,
+            sessionId: o,
+            startTime: r,
             lastActivity: t
           })
-        ), s;
+        ), o;
     }
-    const n = u("session"), o = {
-      sessionId: n,
+    const s = d("session"), n = {
+      sessionId: s,
       startTime: t,
       lastActivity: t
     };
-    return sessionStorage.setItem(h, JSON.stringify(o)), n;
+    return sessionStorage.setItem(S, JSON.stringify(n)), s;
   } catch {
-    return u("session_fallback");
+    return d("session_fallback");
   }
-}, T = (t) => {
-  const e = p(), n = f();
-  return t.debug && console.warn("DotAnalytics Identity Context:", {
+}, $ = (t) => {
+  const e = D(), s = p();
+  return t.debug && console.warn("DotCMS Analytics Identity Context:", {
     sessionId: e,
-    userId: n
+    userId: s
   }), {
-    site_key: t.siteKey,
+    site_auth: t.siteAuth,
     session_id: e,
-    user_id: n
+    user_id: s
   };
-}, w = () => d || (d = {
-  user_language: navigator.language || void 0,
-  doc_encoding: document.characterSet || document.charset || void 0,
-  screen_resolution: typeof screen < "u" && screen.width && screen.height ? `${screen.width}x${screen.height}` : void 0
-}, d), I = () => {
+}, I = () => g || (g = {
+  user_language: navigator.language,
+  doc_encoding: document.characterSet || document.charset,
+  screen_resolution: typeof screen < "u" && screen.width && screen.height ? `${screen.width}x${screen.height}` : ""
+}, g), y = (t) => {
+  const e = t.search;
+  if (u && u.search === e)
+    return u.params;
+  const s = new URLSearchParams(e), n = {};
+  return w.forEach((o) => {
+    const r = s.get(o);
+    if (r) {
+      const a = o.replace("utm_", "");
+      n[a] = r;
+    }
+  }), u = { search: e, params: n }, n;
+}, E = () => {
   try {
-    const t = (/* @__PURE__ */ new Date()).getTimezoneOffset(), e = t > 0 ? "-" : "+", n = Math.abs(t), o = Math.floor(n / 60), s = n % 60;
-    return `${e}${o.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}`;
+    const t = (/* @__PURE__ */ new Date()).getTimezoneOffset(), e = t > 0 ? "-" : "+", s = Math.abs(t), n = Math.floor(s / 60), o = s % 60;
+    return `${e}${n.toString().padStart(2, "0")}:${o.toString().padStart(2, "0")}`;
   } catch {
     return "+00:00";
   }
-}, D = () => {
+}, O = () => {
   try {
-    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");
-    return `${n}-${o}-${s}T${c}:${i}:${g}${e}`;
+    const t = /* @__PURE__ */ new Date(), e = E(), s = t.getFullYear(), n = (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");
+    return `${s}-${n}-${o}T${r}:${a}:${c}${e}`;
   } catch {
     return (/* @__PURE__ */ new Date()).toISOString();
   }
-}, $ = (t, e = typeof window < "u" ? window.location : {}) => {
-  const n = D(), o = w(), { properties: s } = t, { utm: c } = s, i = {
-    url: s.url ?? e.href,
-    doc_encoding: o.doc_encoding,
-    doc_hash: s.hash ?? e.hash ?? "",
+}, C = (t, e = typeof window < "u" ? window.location : {}) => {
+  const s = O(), n = I(), { properties: o } = t, r = {};
+  Object.keys(o).forEach((h) => {
+    _.includes(h) || (r[h] = o[h]);
+  });
+  const a = {
+    url: e.href,
+    doc_encoding: n.doc_encoding,
+    doc_hash: e.hash,
     doc_protocol: e.protocol,
-    doc_search: s.search ?? e.search ?? "",
+    doc_search: e.search,
     doc_host: e.hostname,
-    doc_path: s.path ?? e.pathname,
-    title: s.title ?? (document == null ? void 0 : document.title),
-    language_id: void 0,
-    persona: void 0
-  }, g = {
-    screen_resolution: o.screen_resolution,
-    language: o.user_language,
-    viewport_width: String(s.width),
-    viewport_height: String(s.height)
-  }, a = {};
-  if (c && typeof c == "object") {
-    const r = c;
-    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);
-  }
+    doc_path: e.pathname,
+    title: o.title ?? (document == null ? void 0 : document.title)
+  }, c = {
+    screen_resolution: n.screen_resolution ?? "",
+    language: n.user_language ?? "",
+    viewport_width: String(o.width),
+    viewport_height: String(o.height)
+  }, i = y(e);
   return {
     ...t,
-    page: i,
-    device: g,
-    ...Object.keys(a).length > 0 && { utm: a },
-    local_time: n
+    page: a,
+    device: c,
+    ...Object.keys(i).length > 0 && { utm: i },
+    // Only include custom if there are user-provided properties
+    ...Object.keys(r).length > 0 && { custom: r },
+    local_time: s
   };
 };
 export {
-  $ as enrichPagePayloadOptimized,
-  u as generateSecureId,
-  T as getAnalyticsContext,
-  D as getLocalTime,
-  p as getSessionId,
-  f as getUserId
+  C as enrichPagePayloadOptimized,
+  y as extractUTMParameters,
+  d as generateSecureId,
+  $ as getAnalyticsContext,
+  O as getLocalTime,
+  D as getSessionId,
+  p as getUserId
 };

package/lib/core/shared/models/data.model.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Data models for DotCMS Analytics
+ * Contains interfaces for data structures used in analytics events
+ */
+/**
+ * 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.
+ *
+ * This is an internal type used by utility functions.
+ */
+export interface DotCMSBrowserData {
+    /** 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;
+    /** Viewport size as a string (e.g., "1200x800") */
+    vp_size: string;
+    /** User's preferred language */
+    user_language: string;
+    /** Document encoding */
+    doc_encoding: string;
+    /** Document path */
+    doc_path: string;
+    /** Document host */
+    doc_host: string;
+    /** Document protocol (http/https) */
+    doc_protocol: string;
+    /** Document hash fragment */
+    doc_hash: string;
+    /** Document search parameters */
+    doc_search: string;
+    /** Referrer URL */
+    referrer: string;
+    /** Page title */
+    page_title: string;
+    /** Current page URL */
+    url: string;
+    /** UTM parameters for campaign tracking */
+    utm: DotCMSEventUtmData;
+}
+/**
+ * Analytics context shared across all events in DotCMS.
+ * Contains session and user identification data that provides
+ * continuity across multiple analytics events.
+ */
+export interface DotCMSAnalyticsEventContext {
+    /** The site key for the DotCMS instance */
+    site_auth: 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 DotCMSEventDeviceData {
+    /** Screen resolution as a string (e.g., "1920x1080") */
+    screen_resolution: string;
+    /** User's preferred language */
+    language: string;
+    /** Viewport width in pixels */
+    viewport_width: string;
+    /** Viewport height in pixels */
+    viewport_height: string;
+}
+/**
+ * UTM (Urchin Tracking Module) parameters for DotCMS campaign tracking.
+ * Contains marketing campaign attribution data extracted from URL parameters.
+ */
+export interface DotCMSEventUtmData {
+    /** 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 type DotCMSEventPageData = Pick<DotCMSBrowserData, 'url' | 'doc_path' | 'doc_hash' | 'doc_search' | 'doc_host' | 'doc_protocol' | 'doc_encoding'> & {
+    /** Page title */
+    title: string | undefined;
+    /** Language identifier */
+    language_id?: string;
+    /** Persona identifier */
+    persona?: string;
+};

package/lib/core/shared/models/event.model.d.ts

@@ -0,0 +1,66 @@
+import { DotCMSEventDeviceData, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
+import { DotCMSCustomEventType, DotCMSEventType, DotCMSPredefinedEventType } from '../constants/dot-content-analytics.constants';
+/**
+ * JSON value type for analytics custom data.
+ * Represents any valid JSON value that can be serialized and sent to the analytics server.
+ */
+export type JsonValue = string | number | boolean | null | undefined | JsonObject | JsonArray;
+/**
+ * JSON object type for analytics custom data.
+ */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * JSON array type for analytics custom data.
+ */
+export type JsonArray = JsonValue[];
+/**
+ * Generic base event structure for DotCMS Analytics.
+ * All events share this base structure with customizable event type and data.
+ *
+ * @template TEventType - The type of the event (pageview, custom event name, etc.)
+ * @template TData - The data structure for the event
+ */
+export interface DotCMSEventBase<TEventType extends DotCMSEventType, TData> {
+    /** The type of event being tracked */
+    event_type: TEventType;
+    /** Local timestamp when the event occurred */
+    local_time: string;
+    /** Event-specific data with structured format */
+    data: TData;
+}
+/**
+ * Data structure for pageview events.
+ * Contains page, device, and optional UTM/custom data.
+ */
+export type DotCMSPageViewEventData = {
+    /** Page data associated with the event */
+    page: DotCMSEventPageData;
+    /** Device and browser information */
+    device: DotCMSEventDeviceData;
+    /** UTM parameters for campaign tracking (optional) */
+    utm?: DotCMSEventUtmData;
+    /** Custom data associated with the event (any valid JSON) */
+    custom?: JsonObject;
+};
+/**
+ * Data structure for custom events.
+ * Contains user-defined custom data.
+ */
+export type DotCMSCustomEventData = {
+    /** Custom data associated with the event (any valid JSON) */
+    custom: JsonObject;
+};
+/**
+ * Pageview event structure.
+ */
+export type DotCMSPageViewEvent = DotCMSEventBase<typeof DotCMSPredefinedEventType.PAGEVIEW, DotCMSPageViewEventData>;
+/**
+ * Custom event structure.
+ */
+export type DotCMSCustomEvent = DotCMSEventBase<DotCMSCustomEventType, DotCMSCustomEventData>;
+/**
+ * Union type for all possible analytics events.
+ */
+export type DotCMSEvent = DotCMSPageViewEvent | DotCMSCustomEvent;

package/lib/core/shared/models/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Central export point for all DotCMS Analytics models
+ */
+export * from './data.model';
+export * from './event.model';
+export * from './request.model';
+export * from './library.model';
+declare global {
+    interface Window {
+        __dotAnalyticsCleanup?: () => void;
+    }
+}

package/lib/core/shared/models/library.model.d.ts

@@ -0,0 +1,176 @@
+import { DotCMSAnalyticsEventContext, DotCMSEventDeviceData, DotCMSEventPageData, DotCMSEventUtmData } from './data.model';
+import { JsonObject } from './event.model';
+import { DotCMSAnalyticsRequestBody } from './request.model';
+import { DotCMSCustomEventType } from '../constants';
+/**
+ * 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.
+     * @param payload - Optional custom data to include with the page view (any valid JSON object)
+     */
+    pageView: (payload?: JsonObject) => void;
+    /**
+     * Track a custom event.
+     * @param eventName - The name/type of the event to track
+     * @param payload - Custom data to include with the event (any valid JSON object)
+     */
+    track: (eventName: string, payload: JsonObject) => 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 auth for authenticating with the Analytics service.
+     */
+    siteAuth: string;
+}
+/**
+ * Track event payload with context.
+ * This is the payload for custom track events after the identity plugin adds context.
+ * Used in the track:dot-analytics enricher plugin.
+ */
+export interface AnalyticsTrackPayloadWithContext extends AnalyticsBasePayload {
+    /** The custom event name (any string except 'pageview') */
+    event: DotCMSCustomEventType;
+    /** Analytics context added by identity plugin */
+    context: DotCMSAnalyticsEventContext;
+}
+/**
+ * Parameters passed to DotCMS Analytics plugin methods (after enrichment).
+ * The payload is the complete request body ready to send to the server.
+ */
+export interface DotCMSAnalyticsParams {
+    /** Configuration for the analytics client */
+    config: DotCMSAnalyticsConfig;
+    /** The complete request body */
+    payload: DotCMSAnalyticsRequestBody;
+}
+type AnalyticsBasePayloadType = 'page' | 'track';
+/**
+ * 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 AnalyticsBasePayload {
+    /** The type of analytics event */
+    type: AnalyticsBasePayloadType;
+    /** 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;
+    /** 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 payload with context.
+ * This is the result of enriching the base Analytics.js payload
+ * with context data added by the identity plugin.
+ */
+export interface AnalyticsBasePayloadWithContext extends AnalyticsBasePayload {
+    context: DotCMSAnalyticsEventContext;
+}
+/**
+ * Enriched analytics payload with DotCMS-specific data.
+ * This is the result of enriching the base Analytics.js payload with context (from identity plugin)
+ * and then adding page, device, UTM, and custom data (from enricher plugin).
+ */
+export type EnrichedAnalyticsPayload = AnalyticsBasePayloadWithContext & {
+    /** Page data for the current page */
+    page: DotCMSEventPageData;
+    /** Device and browser information */
+    device: DotCMSEventDeviceData;
+    /** UTM parameters for campaign tracking */
+    utm?: DotCMSEventUtmData;
+    /** Custom data associated with the event (any valid JSON) */
+    custom?: JsonObject;
+    /** Local timestamp when the event occurred */
+    local_time: string;
+};
+/**
+ * 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[];
+    };
+}
+/**
+ * Base parameters structure passed by Analytics.js to plugin hooks.
+ * Contains all the context and data needed for Analytics.js lifecycle hooks
+ * to process and modify analytics events.
+ */
+export interface AnalyticsBaseParams {
+    /** The event payload data */
+    payload: AnalyticsBasePayload;
+    /** 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>;
+    }>;
+}
+export {};

package/lib/core/shared/models/request.model.d.ts

@@ -0,0 +1,24 @@
+import { DotCMSAnalyticsEventContext } from './data.model';
+import { DotCMSCustomEvent, DotCMSEvent, DotCMSPageViewEvent } from './event.model';
+/**
+ * Analytics request body for DotCMS Analytics.
+ * Generic structure sent to the DotCMS analytics server.
+ */
+export interface DotCMSRequestBody<T extends DotCMSEvent> {
+    /** Context information shared across all events */
+    context: DotCMSAnalyticsEventContext;
+    /** Array of analytics events to be tracked */
+    events: T[];
+}
+/**
+ * Specific request body type for PageView events
+ */
+export type DotCMSPageViewRequestBody = DotCMSRequestBody<DotCMSPageViewEvent>;
+/**
+ * Specific request body type for Custom events
+ */
+export type DotCMSCustomEventRequestBody = DotCMSRequestBody<DotCMSCustomEvent>;
+/**
+ * Union type for all possible request bodies
+ */
+export type DotCMSAnalyticsRequestBody = DotCMSPageViewRequestBody | DotCMSCustomEventRequestBody;

package/lib/react/components/DotContentAnalytics.d.ts

@@ -1,5 +1,5 @@
 import { ReactElement } from 'react';
-import { DotCMSAnalyticsConfig } from '../../core/shared/dot-content-analytics.model';
+import { DotCMSAnalyticsConfig } from '../../core/shared/models';
 /**
  * Client bootstrapper for dotCMS Analytics in React/Next.
  * - No UI: initializes the analytics singleton from props or env config.

package/lib/react/hook/useContentAnalytics.d.ts

@@ -1,29 +1,57 @@
-import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../core/shared/dot-content-analytics.model';
+import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../core/shared/models';
 /**
- * Custom hook that handles analytics tracking for anonymous users.
- * Provides methods to track events and page views with automatic timestamp injection.
- * Automatically disables tracking when inside the UVE editor.
+ * React hook for tracking user interactions and page views in your DotCMS application.
+ *
+ * Use this hook to add analytics tracking to your React components. It automatically
+ * handles user sessions, device information, and UTM campaign parameters.
+ *
+ * **Important:** Tracking is automatically disabled when editing content in DotCMS to avoid
+ * polluting your analytics data with editor activity.
  *
  * @example
+ * Basic usage - Track custom events
  * ```tsx
- * function Button({ title, urlTitle }) {
+ * function ProductCard({ title, price }) {
  *   const { track } = useContentAnalytics({
  *     server: 'https://demo.dotcms.com',
- *     siteKey: 'my-site-key',
+ *     siteAuth: 'my-site-auth',
  *     debug: false
  *   });
  *
- *   // Track button click with custom properties
- *   return (
- *     <button onClick={() => track('btn-click', { title, urlTitle })}>
- *       See Details →
- *     </button>
- *   );
+ *   const handleAddToCart = () => {
+ *     track('add-to-cart', {
+ *       product: title,
+ *       price: price
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleAddToCart}>Add to Cart</button>;
+ * }
+ * ```
+ *
+ * @example
+ * Track page views manually
+ * ```tsx
+ * function ArticlePage({ article }) {
+ *   const { pageView } = useContentAnalytics({
+ *     server: 'https://demo.dotcms.com',
+ *     siteKey: 'your-site-key'
+ *   });
+ *
+ *   useEffect(() => {
+ *     pageView({
+ *       category: article.category,
+ *       author: article.author
+ *     });
+ *   }, [article.id]);
  * }
  * ```
  *
- * @param {DotCMSAnalyticsConfig} config - Required configuration object for analytics initialization
- * @returns {DotCMSAnalytics} The analytics instance with tracking capabilities
- * @throws {Error} When analytics initialization fails due to invalid configuration
+ * @param config - Configuration object with server URL and site key
+ * @param config.server - The URL of your DotCMS Analytics server
+ * @param config.siteKey - Your unique site key for authentication
+ * @param config.debug - Optional. Set to true to see analytics events in the console
+ * @returns Object with `track()` and `pageView()` methods for analytics tracking
+ * @throws {Error} If the configuration is invalid (missing server or siteKey)
  */
 export declare const useContentAnalytics: (config: DotCMSAnalyticsConfig) => DotCMSAnalytics;