@dotcms/analytics/lib/core/plugin/impression/dot-analytics.impression-tracker.d.ts

Official JavaScript library for Content Analytics with DotCMS.

import { DotCMSAnalyticsConfig, DotCMSContentImpressionPayload } from '../../shared/models';
/** Callback function for impression events */
export type ImpressionCallback = (eventName: string, payload: DotCMSContentImpressionPayload) => void;
/** Subscription object with unsubscribe method */
export interface ImpressionSubscription {
    unsubscribe: () => void;
}
/**
 * Tracks content impressions using IntersectionObserver and dwell time.
 * Emits events through subscriptions when impressions are detected.
 */
export declare class DotCMSImpressionTracker {
    private observer;
    private mutationObserver;
    private elementImpressionStates;
    private sessionTrackedImpressions;
    private impressionConfig;
    private currentPagePath;
    private subscribers;
    private logger;
    constructor(config: DotCMSAnalyticsConfig);
    /**
     * Subscribe to impression events
     * @param callback - Function called when impression is detected
     * @returns Subscription object with unsubscribe method
     */
    onImpression(callback: ImpressionCallback): ImpressionSubscription;
    /** Notifies all subscribers of an impression */
    private notifySubscribers;
    /** Merges user config with defaults */
    private resolveImpressionConfig;
    /** Initializes tracking: sets up observers, finds contentlets, handles visibility/navigation */
    initialize(): void;
    /** Sets up IntersectionObserver with configured visibility threshold */
    private initializeIntersectionObserver;
    /** Finds contentlets in DOM, validates them, and starts observing (respects maxNodes limit) */
    private findAndObserveContentletElements;
    /** Watches for new contentlets added to DOM (debounced for performance) */
    private initializeDynamicContentDetector;
    /** Cancels all timers when page is hidden (prevents false impressions) */
    private initializePageVisibilityHandler;
    /** Resets tracking on SPA navigation (listens to pushState, replaceState, popstate) */
    private initializePageNavigationHandler;
    /** Handles visibility changes: starts timer on enter, cancels on exit */
    private processIntersectionChanges;
    /** Starts dwell timer; fires impression if element still visible when timer expires */
    private startImpressionDwellTimer;
    /** Cancels active dwell timer (element left viewport before dwell time) */
    private cancelImpressionDwellTimer;
    /** Fires impression event with content & position data (page data added by enricher plugin) */
    private trackAndSendImpression;
    /** Returns skip reason if element is hidden/too small, null if trackable */
    private shouldSkipElement;
    /** Post-dwell check: verifies element still meets visibility threshold */
    private isElementStillVisible;
    /** Checks if impression already fired in current page session */
    private hasBeenTrackedInSession;
    /** Marks impression as tracked (prevents duplicates in same page session) */
    private markImpressionAsTracked;
    /** Cleanup: disconnects observers, clears timers and state */
    cleanup(): void;
}