refactor(sdk-analytics): Consolidate analytics data attributes and simplify Contentlet component (#33948)

## Summary

Consolidates analytics data attributes by moving constants from UVE to
sdk-analytics and simplifies the sdk-react `Contentlet` component by
removing redundant analytics state management. Analytics attributes now
always render using UVE's standard contentlet attributes instead of
separate conditional logic.

## Changes Made

### SDK Analytics (`libs/sdk/analytics`)

- **Moved analytics constants** from `@dotcms/uve/internal` to
`sdk-analytics/constants`:
  - `ANALYTICS_WINDOWS_ACTIVE_KEY` - Analytics active state flag
- `ANALYTICS_WINDOWS_CLEANUP_KEY` - Analytics cleanup function reference
- `CONTENTLET_CLASS` - Renamed from `ANALYTICS_CONTENTLET_CLASS` to
`dotcms-contentlet`

- **Updated data attribute naming** to use standard UVE attributes:
  - `data-dot-analytics-identifier` → `data-dot-identifier`
  - `data-dot-analytics-inode` → `data-dot-inode`
  - `data-dot-analytics-contenttype` → `data-dot-type`
  - `data-dot-analytics-title` → `data-dot-title`
  - `data-dot-analytics-basetype` → `data-dot-basetype`
  - `data-dot-analytics-dom-index` → `data-dot-dom-index`

- **Updated all analytics plugins** to use consolidated constants and
new attribute names:
-
[dot-analytics.content.ts](core-web/libs/sdk/analytics/src/lib/core/dot-analytics.content.ts)
-
[dot-analytics.identity.activity-tracker.ts](core-web/libs/sdk/analytics/src/lib/core/plugin/identity/dot-analytics.identity.activity-tracker.ts)
-
[dot-analytics.impression-tracker.ts](core-web/libs/sdk/analytics/src/lib/core/plugin/impression/dot-analytics.impression-tracker.ts)
-
[dot-analytics.utils.ts](core-web/libs/sdk/analytics/src/lib/core/shared/utils/dot-analytics.utils.ts)

### SDK React (`libs/sdk/react`)

- **Removed `useIsAnalyticsActive` hook**
([useIsAnalyticsActive.ts](core-web/libs/sdk/react/src/lib/next/hooks/useIsAnalyticsActive.ts))
  - No longer needed since analytics attributes always render via UVE

- **Simplified `Contentlet` component**
([Contentlet.tsx:55-78](core-web/libs/sdk/react/src/lib/next/components/Contentlet/Contentlet.tsx#L55-L78)):
  - Removed conditional `analyticsAttributes` useMemo
  - Removed conditional `containerClassName` useMemo
  - Removed `isAnalyticsActive` state check
  - Always applies UVE attributes via `getDotContentletAttributes()`
  - Always applies `CONTENTLET_CLASS` (`dotcms-contentlet`)

- **Updated tests**
([Contentlet.test.tsx](core-web/libs/sdk/react/src/lib/next/__test__/components/Contentlet.test.tsx)):
  - Removed `useIsAnalyticsActive` mock
  - Removed `getDotAnalyticsAttributes` mock
  - Updated assertions to reflect always-rendered attributes
  - Simplified test cases (removed analytics conditional tests)

### SDK UVE (`libs/sdk/uve`)

- **Removed analytics-specific exports** from UVE internal API:
- Removed `getDotAnalyticsAttributes()` function (analytics now uses
standard UVE attributes)
  - Removed `isAnalyticsActive()` function (no longer needed)
- Removed `ANALYTICS_WINDOWS_ACTIVE_KEY` and
`ANALYTICS_WINDOWS_CLEANUP_KEY` constants (moved to sdk-analytics)
  - Removed 50+ lines of analytics-specific tests

## Technical Details

**Problem**: The sdk-react `Contentlet` component had duplicate
analytics attribute logic that conditionally rendered based on
`isAnalyticsActive && !isDevMode`. This created complexity and separated
analytics attributes from UVE's standard contentlet attributes.

**Solution**: 
1. Consolidate analytics constants in `@dotcms/analytics` where they
belong
2. Use UVE's standard `getDotContentletAttributes()` which already
provides all necessary data attributes
3. Remove conditional rendering - analytics attributes always render via
the standard `data-dot-*` attributes
4. Standardize CSS class to `dotcms-contentlet` (used by both UVE and
analytics)

**Benefits**:
- **Simpler component logic** - No analytics state management needed
- **Consistent data attributes** - Single source of truth (UVE)
- **Better separation of concerns** - Analytics constants live in
analytics SDK
- **Always-on tracking** - Analytics attributes always present (no
missed tracking events)

## Breaking Changes

**CSS Class Change**: The analytics contentlet class changed from
`dotcms-analytics-contentlet` to `dotcms-contentlet`. This aligns with
UVE's standard class and should not affect existing implementations as
both classes serve the same selector purpose.

**Data Attribute Changes**: Analytics data attributes now use standard
UVE naming (`data-dot-*` instead of `data-dot-analytics-*`). The
analytics SDK internally handles reading these attributes, so no
client-side changes are needed.

## Testing

- [x] Unit tests updated for `Contentlet` component
- [x] Unit tests updated for analytics plugins (impression tracker,
identity tracker)
- [x] Removed obsolete analytics state tests
- [x] All tests passing

## Related Issues

Closes #33947

## Additional Notes

This refactoring aligns with the strategy to consolidate analytics
functionality and reduce code duplication across the SDK. Future
enhancements can build on this simplified foundation without managing
separate analytics attribute logic.

The change ensures analytics tracking is always active and consistent,
removing edge cases where analytics might be disabled outside Edit Mode.

Author: oidacra

core-web/libs/sdk/analytics/README.md

@@ -247,7 +247,7 @@ The `impressions` option controls automatic tracking of content visibility:
 
 **How it works:**
 
--   ✅ Tracks contentlets marked with `dotcms-analytics-contentlet` class and `data-dot-analytics-*` attributes
+-   ✅ Tracks contentlets marked with `dotcms-contentlet` class and `data-dot-*` attributes (e.g., `data-dot-identifier`, `data-dot-inode`, `data-dot-type`)
 -   ✅ Uses Intersection Observer API for high performance and battery efficiency
 -   ✅ Only fires when element is ≥50% visible for ≥750ms (configurable)
 -   ✅ Only tracks during active tab (respects page visibility)
@@ -299,7 +299,7 @@ The `clicks` option controls automatic tracking of user interactions with conten
 **How it works:**
 
 -   ✅ Tracks clicks on `<a>` and `<button>` elements within contentlets
--   ✅ Contentlets must be marked with `dotcms-analytics-contentlet` class and `data-dot-analytics-*` attributes
+-   ✅ Contentlets must be marked with `dotcms-contentlet` class and `data-dot-*` attributes (e.g., `data-dot-identifier`, `data-dot-inode`, `data-dot-type`)
 -   ✅ Captures semantic attributes (`href`, `aria-label`, `data-*`) and excludes CSS classes
 -   ✅ Throttles rapid clicks to prevent duplicate tracking (300ms fixed)
 -   ✅ One click event per interaction
@@ -341,7 +341,7 @@ The `attributes` array captures additional semantic data in `'key:value'` string
 -   `class` - Already captured as top-level property
 -   `id` - Already captured as top-level property
 -   `href` - Already captured as top-level property
--   `data-dot-analytics-*` - Internal SDK attributes
+-   `data-dot-*` - Internal SDK attributes (e.g., `data-dot-identifier`, `data-dot-inode`, `data-dot-type`)
 
 **Example: Enable click tracking**
 

core-web/libs/sdk/analytics/src/lib/core/dot-analytics.content.ts

@@ -1,13 +1,15 @@
 import { Analytics } from 'analytics';
 
-import { ANALYTICS_WINDOWS_ACTIVE_KEY, ANALYTICS_WINDOWS_CLEANUP_KEY } from '@dotcms/uve/internal';
-
 import { dotAnalyticsClickPlugin } from './plugin/click/dot-analytics.click.plugin';
 import { dotAnalyticsEnricherPlugin } from './plugin/enricher/dot-analytics.enricher.plugin';
 import { dotAnalyticsIdentityPlugin } from './plugin/identity/dot-analytics.identity.plugin';
 import { dotAnalyticsImpressionPlugin } from './plugin/impression/dot-analytics.impression.plugin';
 import { dotAnalytics } from './plugin/main/dot-analytics.plugin';
-import { DotCMSPredefinedEventType } from './shared/constants/dot-analytics.constants';
+import {
+    ANALYTICS_WINDOWS_ACTIVE_KEY,
+    ANALYTICS_WINDOWS_CLEANUP_KEY,
+    DotCMSPredefinedEventType
+} from './shared/constants/dot-analytics.constants';
 import {
     DotCMSAnalytics,
     DotCMSAnalyticsConfig,

core-web/libs/sdk/analytics/src/lib/core/plugin/identity/dot-analytics.identity.activity-tracker.spec.ts

@@ -1,14 +1,16 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import { ANALYTICS_WINDOWS_ACTIVE_KEY, ANALYTICS_WINDOWS_CLEANUP_KEY } from '@dotcms/uve/internal';
-
 import {
     cleanupActivityTracking,
     initializeActivityTracking,
     updateSessionActivity
 } from './dot-analytics.identity.activity-tracker';
 
 import { ACTIVITY_EVENTS } from '../../shared/constants';
+import {
+    ANALYTICS_WINDOWS_ACTIVE_KEY,
+    ANALYTICS_WINDOWS_CLEANUP_KEY
+} from '../../shared/constants/dot-analytics.constants';
 import { DotCMSAnalyticsConfig } from '../../shared/models';
 
 describe('DotCMS Activity Tracker', () => {

core-web/libs/sdk/analytics/src/lib/core/plugin/identity/dot-analytics.identity.activity-tracker.ts

@@ -1,6 +1,9 @@
-import { ANALYTICS_WINDOWS_ACTIVE_KEY, ANALYTICS_WINDOWS_CLEANUP_KEY } from '@dotcms/uve/internal';
-
-import { ACTIVITY_EVENTS, DEFAULT_SESSION_TIMEOUT_MINUTES } from '../../shared/constants';
+import {
+    ACTIVITY_EVENTS,
+    ANALYTICS_WINDOWS_ACTIVE_KEY,
+    ANALYTICS_WINDOWS_CLEANUP_KEY,
+    DEFAULT_SESSION_TIMEOUT_MINUTES
+} from '../../shared/constants';
 import { DotCMSAnalyticsConfig } from '../../shared/models';
 
 // Extend window interface for cleanup function

core-web/libs/sdk/analytics/src/lib/core/plugin/impression/dot-analytics.impression-tracker.spec.ts

@@ -5,7 +5,7 @@ import { getUVEState } from '@dotcms/uve';
 import { DotCMSImpressionTracker } from './dot-analytics.impression-tracker';
 
 import {
-    ANALYTICS_CONTENTLET_CLASS,
+    CONTENTLET_CLASS,
     DEFAULT_IMPRESSION_CONFIG,
     IMPRESSION_EVENT_TYPE
 } from '../../shared/constants/dot-analytics.constants';
@@ -41,12 +41,12 @@ describe('DotCMSImpressionTracker', () => {
         } = {}
     ): HTMLElement => {
         const element = document.createElement('div');
-        element.className = ANALYTICS_CONTENTLET_CLASS;
-        element.dataset.dotAnalyticsIdentifier = identifier;
-        element.dataset.dotAnalyticsInode = options.inode || 'inode-123';
-        element.dataset.dotAnalyticsContenttype = options.contentType || 'Blog';
-        element.dataset.dotAnalyticsTitle = options.title || 'Test Content';
-        element.dataset.dotAnalyticsBasetype = options.baseType || 'CONTENT';
+        element.className = CONTENTLET_CLASS;
+        element.dataset.dotIdentifier = identifier;
+        element.dataset.dotInode = options.inode || 'inode-123';
+        element.dataset.dotType = options.contentType || 'Blog';
+        element.dataset.dotTitle = options.title || 'Test Content';
+        element.dataset.dotBasetype = options.baseType || 'CONTENT';
 
         // Mock getBoundingClientRect
         element.getBoundingClientRect = jest.fn(() => ({
@@ -304,8 +304,8 @@ describe('DotCMSImpressionTracker', () => {
 
         it('should skip elements without identifier', () => {
             const element = document.createElement('div');
-            element.className = ANALYTICS_CONTENTLET_CLASS;
-            // No data-dot-analytics-identifier
+            element.className = CONTENTLET_CLASS;
+            // No data-dot-identifier
             document.body.appendChild(element);
 
             tracker = new DotCMSImpressionTracker(mockConfig);

core-web/libs/sdk/analytics/src/lib/core/plugin/impression/dot-analytics.impression-tracker.ts

@@ -182,8 +182,8 @@ export class DotCMSImpressionTracker {
 
                 // Only observe and initialize if this is a new element
                 if (!this.elementImpressionStates.has(identifier)) {
-                    if (!element.dataset.dotAnalyticsDomIndex) {
-                        element.dataset.dotAnalyticsDomIndex = String(i);
+                    if (!element.dataset.dotDomIndex) {
+                        element.dataset.dotDomIndex = String(i);
                     }
 
                     this.observer.observe(element);
@@ -386,7 +386,7 @@ export class DotCMSImpressionTracker {
 
         // Read cached DOM index instead of expensive query
         // Falls back to -1 if not cached (should never happen in normal flow)
-        const domIndex = parseInt(element.dataset.dotAnalyticsDomIndex || '-1', 10);
+        const domIndex = parseInt(element.dataset.dotDomIndex || '-1', 10);
 
         // Build impression payload (enricher plugin adds page data automatically)
         const impressionPayload: DotCMSContentImpressionPayload = {

core-web/libs/sdk/analytics/src/lib/core/shared/constants/dot-analytics.constants.ts

@@ -185,6 +185,34 @@ export const CLICKABLE_ELEMENTS_SELECTOR = 'a, button';
 export const IMPRESSION_SESSION_KEY = 'dot_analytics_impressions';
 
 /**
- * CSS class selector for trackable contentlets
+ * Window property key for analytics active state
+ * Used to track if analytics is initialized and active
  */
-export const ANALYTICS_CONTENTLET_CLASS = 'dotcms-analytics-contentlet';
+export const ANALYTICS_WINDOWS_ACTIVE_KEY = '__dotAnalyticsActive__';
+
+/**
+ * Window property key for analytics cleanup function
+ * Used to store the cleanup function for analytics instance
+ */
+export const ANALYTICS_WINDOWS_CLEANUP_KEY = '__dotAnalyticsCleanup__';
+
+/**
+ * CSS class selector for contentlet elements
+ *
+ * @important This constant is intentionally duplicated in @dotcms/react SDK
+ * (core-web/libs/sdk/react/src/lib/next/components/Contentlet/Contentlet.tsx).
+ * Both constants MUST have the same value ('dotcms-contentlet') for analytics
+ * tracking to work correctly with React-rendered contentlets.
+ *
+ * This duplication is intentional to maintain SDK independence:
+ * - @dotcms/analytics can be used standalone without React
+ * - @dotcms/react can be used without analytics
+ * - When both are used together, they must share the same class name
+ *
+ * If you need to change this value, you MUST update it in both locations:
+ * 1. This file (analytics SDK)
+ * 2. Contentlet.tsx in React SDK
+ *
+ * @see core-web/libs/sdk/react/src/lib/next/components/Contentlet/Contentlet.tsx
+ */
+export const CONTENTLET_CLASS = 'dotcms-contentlet';

core-web/libs/sdk/analytics/src/lib/core/shared/utils/dot-analytics.utils.ts

@@ -1,9 +1,9 @@
 import { AnalyticsPlugin, PageData } from 'analytics';
 
 import {
-    ANALYTICS_CONTENTLET_CLASS,
     ANALYTICS_JS_DEFAULT_PROPERTIES,
     ANALYTICS_MINIFIED_SCRIPT_NAME,
+    CONTENTLET_CLASS,
     DEFAULT_IMPRESSION_MUTATION_OBSERVER_DEBOUNCE_MS,
     DEFAULT_SESSION_TIMEOUT_MINUTES,
     DotCMSPredefinedEventType,
@@ -635,7 +635,7 @@ export function createThrottle<T extends (...args: unknown[]) => void>(
  * @returns The contentlet identifier or null if not found
  */
 export function extractContentletIdentifier(element: HTMLElement): string | null {
-    return element.dataset.dotAnalyticsIdentifier || null;
+    return element.dataset.dotIdentifier || null;
 }
 
 /**
@@ -645,11 +645,11 @@ export function extractContentletIdentifier(element: HTMLElement): string | null
  */
 export function extractContentletData(element: HTMLElement): ContentletData {
     return {
-        identifier: element.dataset.dotAnalyticsIdentifier || '',
-        inode: element.dataset.dotAnalyticsInode || '',
-        contentType: element.dataset.dotAnalyticsContenttype || '',
-        title: element.dataset.dotAnalyticsTitle || '',
-        baseType: element.dataset.dotAnalyticsBasetype || ''
+        identifier: element.dataset.dotIdentifier || '',
+        inode: element.dataset.dotInode || '',
+        contentType: element.dataset.dotType || '',
+        title: element.dataset.dotTitle || '',
+        baseType: element.dataset.dotBasetype || ''
     };
 }
 
@@ -672,7 +672,7 @@ export const isBrowser = (): boolean => {
  * @returns Array of contentlet HTMLElements
  */
 export const findContentlets = (): HTMLElement[] => {
-    return Array.from(document.querySelectorAll<HTMLElement>(`.${ANALYTICS_CONTENTLET_CLASS}`));
+    return Array.from(document.querySelectorAll<HTMLElement>(`.${CONTENTLET_CLASS}`));
 };
 
 /**
@@ -710,12 +710,12 @@ export const createContentletObserver = (
                 const element = node as HTMLElement;
 
                 // Check if node itself is a contentlet
-                if (element.classList?.contains(ANALYTICS_CONTENTLET_CLASS)) {
+                if (element.classList?.contains(CONTENTLET_CLASS)) {
                     return true;
                 }
 
                 // Check if node contains contentlets
-                return element.querySelector?.(`.${ANALYTICS_CONTENTLET_CLASS}`) !== null;
+                return element.querySelector?.(`.${CONTENTLET_CLASS}`) !== null;
             });
         });
 

core-web/libs/sdk/react/src/lib/next/__test__/components/Contentlet.test.tsx

@@ -2,12 +2,11 @@ import '@testing-library/jest-dom';
 
 import { render, screen } from '@testing-library/react';
 
-import { getDotAnalyticsAttributes, getDotContentletAttributes } from '@dotcms/uve/internal';
+import { getDotContentletAttributes } from '@dotcms/uve/internal';
 
-import { Contentlet } from '../../components/Contentlet/Contentlet';
+import { Contentlet, CONTENTLET_CLASS } from '../../components/Contentlet/Contentlet';
 import { DotCMSPageContext } from '../../contexts/DotCMSPageContext';
 import { useCheckVisibleContent } from '../../hooks/useCheckVisibleContent';
-import { useIsAnalyticsActive } from '../../hooks/useIsAnalyticsActive';
 
 jest.mock('../../components/FallbackComponent/FallbackComponent', () => ({
     FallbackComponent: ({ contentlet }: any) => (
@@ -20,13 +19,9 @@ jest.mock('../../hooks/useCheckVisibleContent', () => ({
     useCheckVisibleContent: jest.fn(() => false)
 }));
 
-jest.mock('../../hooks/useIsAnalyticsActive', () => ({
-    useIsAnalyticsActive: jest.fn(() => false)
-}));
-
 jest.mock('@dotcms/uve/internal', () => ({
     getDotContentletAttributes: jest.fn(() => ({ 'data-custom': 'true' })),
-    getDotAnalyticsAttributes: jest.fn(() => ({ 'data-analytics-custom': 'true' })),
+    CUSTOM_NO_COMPONENT: 'CustomNoComponent',
     DEVELOPMENT_MODE: 'development',
     PRODUCTION_MODE: 'production'
 }));
@@ -42,15 +37,11 @@ describe('Contentlet', () => {
     };
 
     const useCheckVisibleContentMock = useCheckVisibleContent as jest.Mock;
-    const useIsAnalyticsActiveMock = useIsAnalyticsActive as jest.Mock;
     const getDotContentletAttributesMock = getDotContentletAttributes as jest.Mock;
-    const getDotAnalyticsAttributesMock = getDotAnalyticsAttributes as jest.Mock;
 
     beforeEach(() => {
         useCheckVisibleContentMock.mockReturnValue(false);
-        useIsAnalyticsActiveMock.mockReturnValue(false);
         getDotContentletAttributesMock.mockClear();
-        getDotAnalyticsAttributesMock.mockClear();
     });
 
     test('should render fallback component when no custom component exists', () => {
@@ -64,6 +55,7 @@ describe('Contentlet', () => {
 
         const containerDiv = screen.getByTestId('fallback').parentElement;
         expect(containerDiv).toHaveAttribute('data-dot-object', 'contentlet');
+        expect(containerDiv).toHaveClass(CONTENTLET_CLASS);
 
         expect(containerDiv).toHaveStyle('min-height: 4rem');
         expect(getDotContentletAttributesMock).toHaveBeenCalledWith(dummyContentlet, 'container-1');
@@ -98,12 +90,13 @@ describe('Contentlet', () => {
             container: 'container-1'
         });
 
-        expect(getDotContentletAttributes).not.toHaveBeenCalled();
+        // UVE attributes should always be called
+        expect(getDotContentletAttributesMock).toHaveBeenCalledWith(dummyContentlet, 'container-1');
 
         const containerDiv = container.querySelector(
             '[data-dot-object="contentlet"]'
         ) as HTMLElement;
-        expect(containerDiv.className).toBe('');
+        expect(containerDiv.className).toBe(CONTENTLET_CLASS);
     });
 
     test('should not apply minHeight style if useCheckVisibleContent returns true', () => {
@@ -120,49 +113,39 @@ describe('Contentlet', () => {
         expect(containerDiv).not.toHaveStyle('min-height: 4rem');
     });
 
-    test('should add analytics attributes when isAnalyticsActive is true in production', () => {
-        useIsAnalyticsActiveMock.mockReturnValue(true);
-
+    test('should always apply UVE attributes in production', () => {
         const contextValue = {
             mode: 'production',
             userComponents: {}
         };
 
         renderContentlet(contextValue, { contentlet: dummyContentlet, container: 'container-1' });
 
-        // UVE attributes should NOT be called in production
-        expect(getDotContentletAttributesMock).not.toHaveBeenCalled();
-        // Analytics attributes SHOULD be called when analytics is active
-        expect(getDotAnalyticsAttributesMock).toHaveBeenCalledWith(dummyContentlet);
+        // UVE attributes should always be called
+        expect(getDotContentletAttributesMock).toHaveBeenCalledWith(dummyContentlet, 'container-1');
     });
 
-    test('should not add any data attributes when both isDevMode and isAnalyticsActive are false', () => {
-        useIsAnalyticsActiveMock.mockReturnValue(false);
-
+    test('should always apply UVE attributes even when isDevMode is false', () => {
         const contextValue = {
             mode: 'production',
             userComponents: {}
         };
 
         renderContentlet(contextValue, { contentlet: dummyContentlet, container: 'container-1' });
 
-        expect(getDotContentletAttributesMock).not.toHaveBeenCalled();
-        expect(getDotAnalyticsAttributesMock).not.toHaveBeenCalled();
+        // UVE attributes should always be called
+        expect(getDotContentletAttributesMock).toHaveBeenCalledWith(dummyContentlet, 'container-1');
     });
 
-    test('should NOT add analytics attributes when in development mode (UVE)', () => {
-        useIsAnalyticsActiveMock.mockReturnValue(true);
-
+    test('should always apply UVE attributes in development mode (UVE)', () => {
         const contextValue = {
             mode: 'development',
             userComponents: {}
         };
 
         renderContentlet(contextValue, { contentlet: dummyContentlet, container: 'container-1' });
 
-        // UVE attributes should be called in development
+        // UVE attributes should always be called
         expect(getDotContentletAttributesMock).toHaveBeenCalledWith(dummyContentlet, 'container-1');
-        // Analytics attributes should NOT be called in development mode (even if analytics is active)
-        expect(getDotAnalyticsAttributesMock).not.toHaveBeenCalled();
     });
 });