@dotcms/analytics
Version:
Official JavaScript library for Content Analytics with DotCMS.
109 lines (108 loc) • 3.8 kB
TypeScript
import { DotCMSAnalyticsConfig, DotCMSContentClickPayload } from '../../shared/models';
/** Callback function for click events */
export type ClickCallback = (eventName: string, payload: DotCMSContentClickPayload) => void;
/** Subscription object with unsubscribe method */
export interface ClickSubscription {
unsubscribe: () => void;
}
/**
* Tracks content clicks using event listeners on contentlet containers.
* Detects clicks on <a> and <button> elements inside contentlets and fires events.
*
* Features:
* - Attaches event listeners to contentlet containers
* - Tracks clicks on anchor and button elements only
* - Uses MutationObserver to detect dynamically added content
* - Throttles rapid clicks to prevent duplicates (300ms)
* - Subscription-based event system for decoupling
*
* @example
* ```typescript
* const tracker = new DotCMSClickTracker(config);
* const subscription = tracker.onClick((eventName, payload) => {
* console.log('Click detected:', payload);
* });
* tracker.initialize();
* // Later: subscription.unsubscribe();
* ```
*/
export declare class DotCMSClickTracker {
private config;
private mutationObserver;
private lastClickTime;
private logger;
private subscribers;
private trackedElements;
private elementHandlers;
constructor(config: DotCMSAnalyticsConfig);
/**
* Subscribe to click events
* @param callback - Function called when click is detected
* @returns Subscription object with unsubscribe method
*/
onClick(callback: ClickCallback): ClickSubscription;
/**
* Notifies all subscribers of a click event
* @param eventName - Name of the event (e.g., 'content_click')
* @param payload - Click event payload with content and element data
*/
private notifySubscribers;
/**
* Initialize click tracking system
*
* Performs the following:
* - Validates browser environment
* - Scans for existing contentlets after a delay (100ms)
* - Sets up MutationObserver for dynamic content
*
* The delay allows React/Next.js to finish initial rendering
* before attaching listeners.
*/
initialize(): void;
/**
* Attach click listener to a contentlet container
*
* Skips if element already has a listener attached.
* The listener delegates to handleContentletClick which:
* - Finds clicked anchor/button elements
* - Extracts contentlet and element data
* - Applies throttling (300ms)
* - Notifies subscribers
*
* @param element - Contentlet container element to track
*/
private attachClickListener;
/**
* Find and attach listeners to all contentlet elements in the DOM
*
* Scans the entire document for elements with the
* `.dotcms-analytics-contentlet` class and attaches click
* listeners if not already tracked.
*
* Called during initialization and whenever DOM mutations are detected.
*/
private findAndAttachListeners;
/**
* Initialize MutationObserver to detect new contentlet containers
* Uses same simple strategy as impression tracker - no complex filtering
*/
private initializeMutationObserver;
/**
* Remove all click listeners from tracked contentlets
*
* Iterates through all contentlet elements and removes their
* click event handlers, cleaning up WeakMap references.
*/
private removeAllListeners;
/**
* Cleanup all resources used by the click tracker
*
* Performs:
* - Removes all event listeners from contentlets
* - Disconnects MutationObserver
* - Clears internal references
*
* Should be called when the plugin is disabled or on page unload.
*/
cleanup(): void;
}