use-page-view/dist/use-page-view-vAkJzz-K.d.ts

A React hook for tracking page views and user engagement time. This hook provides real-time tracking of how long users spend on a page, their activity status, and the ability to persist time tracking across page reloads.

//#region src/hooks/use-page-view.d.ts
/**
 * Data structure for page view tracking
 */
interface PageViewData {
  pageId: string;
  userId?: string;
  timeSpent: number;
  isActive: boolean;
}
/**
 * Configuration options for the page view tracker
 */
interface UsePageViewOptions {
  /** Unique identifier for the page being tracked */
  pageId: string;
  /** Optional user identifier if user is logged in */
  userId?: string;
  /** Minimum time in seconds before recording a view (default: 5) */
  minTimeThreshold?: number;
  /** How often to send updates in seconds (default: 30) */
  heartbeatInterval?: number;
  /** Time in seconds before user is considered inactive (default: 30) */
  inactivityThreshold?: number;
  /** Callback function to handle page view data */
  onPageView?: (data: PageViewData) => void;
  /** Track only the initial view (default: false) */
  trackOnce?: boolean;
  /** Minimum time in seconds before recording a view when trackOnce is true (default: 0) */
  trackOnceDelay?: number;
}
/**
 * A React hook to track page views and user engagement time. It monitors user activity,
 * page visibility, and time spent on the page, providing real-time updates through
 * a callback function.
 *
 * @param options - Configuration options for the page view tracker
 * @param options.pageId - Unique identifier for the page being tracked
 * @param options.userId - Optional user identifier if user is logged in
 * @param options.minTimeThreshold - Minimum time in seconds before recording a view (default: 5)
 * @param options.heartbeatInterval - How often to send updates in seconds (default: 30)
 * @param options.inactivityThreshold - Time in seconds before user is considered inactive (default: 30)
 * @param options.onPageView - Callback function to handle page view data
 * @param options.trackOnce - Track only the initial view (default: false)
 * @param options.trackOnceDelay - Minimum time in seconds before recording a view when trackOnce is true (default: 0)
 *
 * @returns An object containing:
 *   - timeSpent: number - Total time spent on the page in seconds
 *   - isActive: boolean - Whether the user is currently active on the page
 *
 * @example
 * ```tsx
 * // Example of a time formatting function
 * function formatTime(seconds: number): string {
 *   const mins = Math.floor(seconds / 60);
 *   const secs = seconds % 60;
 *   return `${mins}:${secs.toString().padStart(2, '0')}`;
 * }
 *
 * const handlePageView = React.useCallback(async (data: PageViewData) => {
 *   await fetch('/api/track-page-view', {
 *     method: 'POST',
 *     body: JSON.stringify(data)
 *   });
 * }, []);
 *
 * function BlogPost() {
 *   const { timeSpent, isActive } = usePageView({
 *     pageId: 'blog-post-123',
 *     userId: 'user-456',
 *     minTimeThreshold: 10,
 *     heartbeatInterval: 30,
 *     inactivityThreshold: 60, // User considered inactive after 60 seconds
 *     onPageView: handlePageView
 *   });
 *
 *   return (
 *     <div>
 *       <div>
 *         Time: {formatTime(timeSpent)} {isActive ? '🟢' : '🔴'}
 *       </div>
 *       <article>Your content here...</article>
 *     </div>
 *   );
 * }
 * ```
 */
declare function usePageView({
  pageId,
  userId,
  minTimeThreshold,
  heartbeatInterval,
  inactivityThreshold,
  onPageView,
  trackOnce,
  trackOnceDelay
}: UsePageViewOptions): {
  timeSpent: number;
  isActive: boolean;
};
//#endregion
export { PageViewData, usePageView };