@dotcms/analytics 1.0.6 → 1.1.1

package/README.md

@@ -4,16 +4,15 @@ Lightweight JavaScript SDK for tracking content-aware events in dotCMS. Works in
 
 ## 🚀 Quick Start
 
-### Vanilla JavaScript
-
-**CDN (Script Tag - Auto Page View)**
+### Standalone (Script Tag)
 
 ```html
 <script
     src="ca.min.js"
-    data-server="https://demo.dotcms.com"
-    data-site-key="SITE_KEY"
-    data-auto-page-view></script>
+    data-analytics-server="https://demo.dotcms.com"
+    data-analytics-auth="SITE_KEY"
+    data-analytics-auto-page-view="true"
+    data-analytics-debug="false"></script>
 ```
 
 **npm (ES Module)**
@@ -40,17 +39,17 @@ npm install @dotcms/analytics
 ```
 
 ```tsx
-import { DotContentAnalyticsProvider } from '@dotcms/analytics/react';
+import { DotContentAnalytics } from '@dotcms/analytics/react';
 
 const config = {
     siteKey: 'SITE_KEY',
     server: 'https://demo.dotcms.com',
-    autoPageView: true // Optional, default is true
+    autoPageView: true // Optional, default is true in React
 };
 
-<DotContentAnalyticsProvider config={config}>
-    <App />
-</DotContentAnalyticsProvider>;
+export function AppRoot() {
+    return <DotContentAnalytics config={config} />;
+}
 ```
 
 ## 📘 Core Concepts
@@ -61,7 +60,8 @@ Track any user action as an event using `track('event-name', { payload })`.
 
 ### Page Views
 
-Tracked automatically (or manually) on route changes.
+-   React: Automatically tracked on route changes when using `DotContentAnalytics`.
+-   Standalone: Auto-tracked only if `data-analytics-auto-page-view="true"`; otherwise call `window.dotAnalytics.pageView()`.
 
 ### Sessions
 
@@ -76,13 +76,12 @@ Tracked automatically (or manually) on route changes.
 
 ## ⚙️ Configuration Options
 
-| Option         | Type       | Required | Default | Description                            |
-| -------------- | ---------- | -------- | ------- | -------------------------------------- |
-| `siteKey`      | `string`   | ✅       | -       | Site key from dotCMS Analytics app     |
-| `server`       | `string`   | ✅       | -       | Your dotCMS server URL                 |
-| `debug`        | `boolean`  | ❌       | `false` | Enable verbose logging                 |
-| `autoPageView` | `boolean`  | ❌       | `true`  | Auto track page views on route changes |
-| `redirectFn`   | `function` | ❌       | -       | Custom handler for redirects           |
+| Option         | Type      | Required | Default                             | Description                            |
+| -------------- | --------- | -------- | ----------------------------------- | -------------------------------------- |
+| `siteKey`      | `string`  | ✅       | -                                   | Site key from dotCMS Analytics app     |
+| `server`       | `string`  | ✅       | -                                   | Your dotCMS server URL                 |
+| `debug`        | `boolean` | ❌       | `false`                             | Enable verbose logging                 |
+| `autoPageView` | `boolean` | ❌       | React: `true` / Standalone: `false` | Auto track page views on route changes |
 
 ## 🛠️ Usage Examples
 
@@ -119,14 +118,25 @@ analytics.pageView();
 **Track Events**
 
 ```tsx
-const { track } = useContentAnalytics();
+import { useContentAnalytics } from '@dotcms/analytics/react';
+
+const { track } = useContentAnalytics({
+    siteKey: 'SITE_KEY',
+    server: 'https://demo.dotcms.com'
+});
+
 track('cta-click', { label: 'Download PDF' });
 ```
 
 **Manual Page View**
 
 ```tsx
-const { pageView } = useContentAnalytics();
+import { useContentAnalytics } from '@dotcms/analytics/react';
+
+const { pageView } = useContentAnalytics({
+    siteKey: 'SITE_KEY',
+    server: 'https://demo.dotcms.com'
+});
 useEffect(() => {
     pageView();
 }, []);
@@ -135,8 +145,15 @@ useEffect(() => {
 **Advanced: Manual Tracking with Router**
 
 ```tsx
+// Next.js App Router is automatically tracked by <DotContentAnalytics />
+// For other routers, you can call pageView on location change
 import { useLocation } from 'react-router-dom';
-const { pageView } = useContentAnalytics();
+import { useContentAnalytics } from '@dotcms/analytics/react';
+
+const { pageView } = useContentAnalytics({
+    siteKey: 'SITE_KEY',
+    server: 'https://demo.dotcms.com'
+});
 const location = useLocation();
 
 useEffect(() => {
@@ -182,6 +199,13 @@ Analytics are disabled when inside the dotCMS editor.
 -   Check network requests to: `https://your-server/api/v1/analytics/content/event`
 -   Avoid using inside dotCMS editor (auto-disabled)
 
+Standalone attributes to verify:
+
+-   `data-analytics-auth` (required)
+-   `data-analytics-server` (optional, defaults to current origin)
+-   `data-analytics-auto-page-view` (`true` to enable)
+-   `data-analytics-debug` (`true` to enable)
+
 ## Roadmap
 
 -   Scroll depth & file download tracking

package/lib/{dotAnalytics → core}/shared/dot-content-analytics.constants.d.ts

@@ -31,3 +31,7 @@ export declare const USER_ID_KEY = "dot_analytics_user_id";
  * - 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/{dotAnalytics → core}/shared/dot-content-analytics.utils.d.ts

@@ -31,13 +31,20 @@ export declare const getSessionId: () => string;
  */
 export declare const getAnalyticsContext: (config: DotCMSAnalyticsConfig) => DotCMSAnalyticsContext;
 /**
- * Retrieves analytics attributes from a given script element.
+ * Configuration result with warnings for analytics setup
  */
-export declare const getDataAnalyticsAttributes: () => DotCMSAnalyticsConfig;
+export interface AnalyticsConfigResult {
+    config: DotCMSAnalyticsConfig;
+    warnings?: string[];
+    missingAttributes?: string[];
+    hasIssues: boolean;
+}
 /**
- * Gets the analytics script tag from the DOM
+ * Gets analytics configuration, always returns a config (with defaults if needed)
+ * - If no data-analytics-server attribute is found, uses the current domain as the server endpoint
+ * - Both debug and autoPageView default to false (must be explicitly set to "true")
  */
-export declare const getAnalyticsScriptTag: () => HTMLScriptElement;
+export declare const getAnalyticsConfig: () => DotCMSAnalyticsConfig;
 /**
  * Retrieves the browser event data - optimized but accurate.
  */

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

@@ -1,5 +1,5 @@
 import { ReactElement } from 'react';
-import { DotCMSAnalyticsConfig } from '../../dotAnalytics/shared/dot-content-analytics.model';
+import { DotCMSAnalyticsConfig } from '../../core/shared/dot-content-analytics.model';
 /**
  * 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,4 +1,4 @@
-import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../dotAnalytics/shared/dot-content-analytics.model';
+import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../core/shared/dot-content-analytics.model';
 /**
  * Custom hook that handles analytics tracking for anonymous users.
  * Provides methods to track events and page views with automatic timestamp injection.

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

@@ -1,4 +1,4 @@
-import { DotCMSAnalytics } from '../../dotAnalytics/shared/dot-content-analytics.model';
+import { DotCMSAnalytics } from '../../core/shared/dot-content-analytics.model';
 /**
  * Tracks page views on route changes using Next.js App Router signals.
  * - Fires a single pageView per unique path+search.

package/lib/react/internal/utils.d.ts

@@ -1,4 +1,4 @@
-import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../dotAnalytics/shared/dot-content-analytics.model';
+import { DotCMSAnalytics, DotCMSAnalyticsConfig } from '../../core/shared/dot-content-analytics.model';
 /**
  * Initializes analytics with explicit configuration.
  * Resets singleton if config changes.

package/lib/react/internal/utils.js

@@ -1,4 +1,4 @@
-import { initializeContentAnalytics as r } from "../../dotAnalytics/dot-content-analytics.js";
+import { initializeContentAnalytics as r } from "../../core/dot-content-analytics.js";
 let e, t;
 const s = (i) => (t && (t.server !== i.server || t.siteKey !== i.siteKey) && (e = void 0), e !== void 0 || (t = i, e = r(i)), e);
 export {

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

@@ -1,3 +1,3 @@
-export type { DotCMSAnalyticsConfig } from '../dotAnalytics/shared/dot-content-analytics.model';
+export type { DotCMSAnalyticsConfig } from '../core/shared/dot-content-analytics.model';
 export { DotContentAnalytics } from './components/DotContentAnalytics';
 export { useContentAnalytics } from './hook/useContentAnalytics';

package/lib/standalone.d.ts

@@ -1,5 +1,5 @@
-import { ANALYTICS_WINDOWS_KEY } from './dotAnalytics/shared/dot-content-analytics.constants';
-import { DotCMSAnalytics } from './dotAnalytics/shared/dot-content-analytics.model';
+import { ANALYTICS_WINDOWS_KEY } from './core/shared/dot-content-analytics.constants';
+import { DotCMSAnalytics } from './core/shared/dot-content-analytics.model';
 declare global {
     interface Window {
         [ANALYTICS_WINDOWS_KEY]: DotCMSAnalytics | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/analytics",
-  "version": "1.0.6",
+  "version": "1.1.1",
   "description": "Official JavaScript library for Content Analytics with DotCMS.",
   "repository": {
     "type": "git",