use-page-view 1.0.0 → 1.0.1

package/README.md

@@ -1,9 +1,10 @@
 # use-page-view
 
-A React hook for tracking page views and user engagement time. This hook provides real-time monitoring of user activity, page visibility, and time spent on pages.
+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 flexible callbacks for implementing custom persistence and analytics.
 
 [![npm version](https://img.shields.io/npm/v/use-page-view.svg)](https://www.npmjs.com/package/use-page-view)
 [![npm downloads](https://img.shields.io/npm/dm/use-page-view.svg)](https://www.npmjs.com/package/use-page-view)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/use-page-view)](https://bundlephobia.com/package/use-page-view)
 [![License](https://img.shields.io/npm/l/use-page-view.svg)](https://github.com/christophersesugh/use-page-view/blob/main/LICENSE)
 [![CI Status](https://img.shields.io/github/actions/workflow/status/christophersesugh/use-page-view/ci.yml)](https://github.com/christophersesugh/use-page-view/actions)
 [![Coverage](https://img.shields.io/codecov/c/github/christophersesugh/use-page-view)](https://codecov.io/gh/christophersesugh/use-page-view)
@@ -12,10 +13,13 @@ A React hook for tracking page views and user engagement time. This hook provide
 
 - 📊 Track time spent on pages
 - 👀 Monitor user activity and page visibility
-- ⏱️ Configurable tracking intervals
-- 🔄 Real-time updates
-- 🎯 Support for both continuous and one-time tracking
-- 🛡️ TypeScript support
+- 🔄 Periodic updates through callback
+- ⏱️ Configurable thresholds and intervals
+- 🎯 Support for one-time tracking
+- 🔑 User identification support
+- 🚀 Lightweight with minimal overhead
+- 🌐 SSR/React Router/Next.js compatible
+- 🛠️ Flexible - implement your own persistence strategy
 
 ## Installation
 
@@ -27,7 +31,37 @@ yarn add use-page-view
 pnpm add use-page-view
 ```
 
-## Basic Usage
+## Quick Start
+
+```tsx
+import { usePageView } from 'use-page-view';
+
+function MyPage() {
+  const { timeSpent, isActive } = usePageView({
+    pageId: 'my-page',
+    onPageView: (data) => console.log('Page view:', data),
+  });
+
+  return (
+    <div>
+      <h1>My Page</h1>
+      <p>
+        Time spent: {timeSpent}s {isActive ? '🟢 Active' : '🔴 Inactive'}
+      </p>
+    </div>
+  );
+}
+```
+
+## Compatibility
+
+- **React**: 16.8+ (hooks support required)
+- **TypeScript**: Full TypeScript support included
+- **Browsers**: Modern browsers
+- **SSR**: Compatible with React Router, Next.js and other SSR frameworks
+- **React Native**: Not supported (web-only)
+
+## Usage
 
 ```tsx
 import { usePageView } from 'use-page-view';
@@ -35,170 +69,212 @@ import { usePageView } from 'use-page-view';
 function BlogPost() {
   const { timeSpent, isActive } = usePageView({
     pageId: 'blog-post-123',
-    onPageView: (data) => {
-      // Handle page view data
-      console.log(data);
+    userId: 'user-456', // Optional
+    minTimeThreshold: 10, // Minimum time before recording (seconds)
+    heartbeatInterval: 30, // How often to send updates (seconds)
+    inactivityThreshold: 60, // Time before user is considered inactive (seconds)
+    onPageView: async (data) => {
+      try {
+        await fetch('/api/track-page-view', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(data),
+        });
+      } catch (error) {
+        console.error('Failed to track page view:', error);
+      }
     },
   });
 
   return (
     <div>
       <div>
-        Time spent: {timeSpent}s {isActive ? '🟢' : '🔴'}
+        Time: {formatTime(timeSpent)} {isActive ? '🟢' : '🔴'}
       </div>
       <article>Your content here...</article>
     </div>
   );
 }
-```
 
-## API Reference
+// Helper function to format time
+function formatTime(seconds: number): string {
+  const mins = Math.floor(seconds / 60);
+  const secs = seconds % 60;
+  return `${mins}:${secs.toString().padStart(2, '0')}`;
+}
+```
 
-### Parameters
+## API
 
-The `usePageView` hook accepts an options object with the following properties:
+### usePageView(options)
 
-| Parameter             | Type                           | Required | Default | Description                                                            |
-| --------------------- | ------------------------------ | -------- | ------- | ---------------------------------------------------------------------- |
-| `pageId`              | `string`                       | Yes      | -       | Unique identifier for the page being tracked                           |
-| `userId`              | `string`                       | No       | -       | Optional user identifier if user is logged in                          |
-| `minTimeThreshold`    | `number`                       | No       | `5`     | Minimum time in seconds before recording a view                        |
-| `heartbeatInterval`   | `number`                       | No       | `30`    | How often to send updates in seconds                                   |
-| `inactivityThreshold` | `number`                       | No       | `30`    | Time in seconds before user is considered inactive                     |
-| `onPageView`          | `(data: PageViewData) => void` | No       | -       | Callback function to handle page view data                             |
-| `trackOnce`           | `boolean`                      | No       | `false` | Track only the initial view                                            |
-| `trackOnceDelay`      | `number`                       | No       | `0`     | Minimum time in seconds before recording a view when trackOnce is true |
+#### Options
 
-### Return Value
+| Option                | Type                           | Default  | Description                                                            |
+| --------------------- | ------------------------------ | -------- | ---------------------------------------------------------------------- |
+| `pageId`              | `string`                       | Required | Unique identifier for the page being tracked                           |
+| `userId`              | `string`                       | Optional | User identifier if user is logged in                                   |
+| `minTimeThreshold`    | `number`                       | `5`      | Minimum time in seconds before recording a view                        |
+| `heartbeatInterval`   | `number`                       | `30`     | How often to send updates in seconds                                   |
+| `inactivityThreshold` | `number`                       | `30`     | Time in seconds before user is considered inactive                     |
+| `onPageView`          | `(data: PageViewData) => void` | Optional | Callback function to handle page view data                             |
+| `trackOnce`           | `boolean`                      | `false`  | Track only the initial view                                            |
+| `trackOnceDelay`      | `number`                       | `0`      | Minimum time in seconds before recording a view when trackOnce is true |
 
-The hook returns an object with the following properties:
+#### Returns
 
 | Property    | Type      | Description                                      |
 | ----------- | --------- | ------------------------------------------------ |
 | `timeSpent` | `number`  | Total time spent on the page in seconds          |
 | `isActive`  | `boolean` | Whether the user is currently active on the page |
 
-### PageViewData Interface
-
-The `onPageView` callback receives a `PageViewData` object with the following structure:
+### PageViewData
 
 ```typescript
 interface PageViewData {
-  pageId: string; // The page identifier
-  userId?: string; // Optional user identifier
-  timeSpent: number; // Time spent in seconds
-  isActive: boolean; // Whether the user is active
+  pageId: string;
+  userId?: string;
+  timeSpent: number;
+  isActive: boolean;
 }
 ```
 
-## Advanced Usage
-
-### Tracking User-Specific Views
-
-```tsx
-function UserProfile() {
-  const { timeSpent, isActive } = usePageView({
-    pageId: 'user-profile',
-    userId: 'user-123', // Track for specific user
-    onPageView: (data) => {
-      // Send to your analytics service
-      analytics.trackPageView(data);
-    },
-  });
-}
-```
+## Examples
 
-### Custom Tracking Intervals
+### Basic Usage
 
 ```tsx
 function Article() {
   const { timeSpent, isActive } = usePageView({
-    pageId: 'article-456',
-    minTimeThreshold: 10, // Only track after 10 seconds
-    heartbeatInterval: 60, // Send updates every minute
-    inactivityThreshold: 120, // Consider user inactive after 2 minutes
+    pageId: 'article-789',
     onPageView: (data) => {
-      // Handle page view data
+      console.log('Article view:', data);
     },
   });
+
+  return (
+    <div>
+      <h1>Article Title</h1>
+      <div>Time spent: {formatTime(timeSpent)}</div>
+      <p>Article content...</p>
+    </div>
+  );
 }
 ```
 
-### One-Time Tracking
+### One-time Tracking
 
 ```tsx
 function LandingPage() {
   const { timeSpent, isActive } = usePageView({
     pageId: 'landing-page',
-    trackOnce: true, // Only track the initial view
-    trackOnceDelay: 5, // Wait 5 seconds before tracking
+    trackOnce: true,
+    trackOnceDelay: 30, // Track after 30 seconds
     onPageView: (data) => {
-      // Handle initial page view
+      analytics.track('landing_page_view', data);
     },
   });
+
+  return (
+    <div>
+      <h1>Welcome</h1>
+      <div>Time on page: {formatTime(timeSpent)}</div>
+    </div>
+  );
 }
 ```
 
-### Custom Time Formatting
+### Error Handling
 
 ```tsx
-function formatTime(seconds: number): string {
-  const mins = Math.floor(seconds / 60);
-  const secs = seconds % 60;
-  return `${mins}:${secs.toString().padStart(2, '0')}`;
-}
-
-function BlogPost() {
+function PageWithErrorHandling() {
   const { timeSpent, isActive } = usePageView({
-    pageId: 'blog-post-123',
-    onPageView: (data) => {
-      // Handle page view data
+    pageId: 'important-page',
+    onPageView: async (data) => {
+      try {
+        const response = await fetch('/api/analytics', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(data),
+        });
+
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+      } catch (error) {
+        console.error('Analytics tracking failed:', error);
+        // Optionally queue for retry or use alternative tracking
+      }
     },
   });
 
-  return (
-    <div>
-      <div>
-        Time: {formatTime(timeSpent)} {isActive ? '🟢' : '🔴'}
-      </div>
-    </div>
-  );
+  return <div>Your page content</div>;
 }
 ```
 
-## Best Practices
+## Features in Detail
 
-1. **Unique Page IDs**: Always use unique identifiers for each page to ensure accurate tracking.
+### Time Tracking
 
-2. **User Identification**: Include `userId` when tracking authenticated users for better analytics.
+- Tracks total time spent on the page
+- Updates every second
+- Handles browser tab switching and page visibility changes
+- Supports custom initial time values for persistence scenarios
 
-3. **Performance**:
+### Activity Monitoring
 
-   - Use appropriate `heartbeatInterval` values to balance real-time updates with performance
-   - Consider using `trackOnce` for pages where continuous tracking isn't needed
+- Detects user activity through mouse, keyboard, and touch events
+- Monitors page visibility changes
+- Updates active status based on user engagement
+- Configurable inactivity threshold
 
-4. **Error Handling**: Always implement error handling in your `onPageView` callback:
+### Flexible Persistence
 
-```tsx
-const handlePageView = async (data: PageViewData) => {
-  try {
-    await analytics.trackPageView(data);
-  } catch (error) {
-    console.error('Failed to track page view:', error);
-    // Implement fallback or retry logic
-  }
-};
-```
+- No built-in persistence to keep the library lightweight
+- Easy to implement custom persistence strategies
+
+### Callback System
+
+- Periodic updates through `onPageView` callback
+- Configurable update interval with `heartbeatInterval`
+- Minimum time threshold with `minTimeThreshold`
+- One-time tracking option with `trackOnce`
+
+## Performance
+
+- **Minimal overhead**: Efficient event handling with automatic cleanup
+- **Memory efficient**: Uses `requestIdleCallback` when available
+- **Bundle size**: < 5KB minified + gzipped
+- **No dependencies**: Zero external dependencies for maximum compatibility
+- **Automatic cleanup**: All event listeners and timers are cleaned up on unmount
+
+## FAQ
+
+**Q: Does this work with SSR/React Router/Next.js?**
+A: Yes, the hook safely handles server-side rendering by checking for browser environment before initializing.
+
+**Q: How do I persist time tracking across page reloads?**
+A: Implement your own persistence strategy using the examples above. You can use localStorage, sessionStorage, databases, or any other storage method that fits your needs.
+
+**Q: How accurate is the time tracking?**
+A: Time tracking is updated every second and accounts for page visibility changes and user inactivity.
+
+**Q: Can I track multiple pages in the same app?**
+A: Yes, use different `pageId` values for each page or component you want to track separately.
+
+**Q: Does this affect my app's performance?**
+A: No, the hook uses efficient event handling and cleanup. The bundle size is minimal (< 3KB).
 
-## Browser Support
+**Q: What events are considered "activity"?**
+A: Mouse movement, clicks, keyboard input, touch events, and scroll events are all considered user activity.
 
-The hook uses the following browser APIs:
+**Q: Why doesn't the hook include built-in localStorage support?**
+A: To keep the library lightweight and flexible. Different applications have different persistence needs, and this approach allows you to implement exactly what you need without bloating the core library.
 
-- `document.visibilitychange`
-- `window.addEventListener` for user activity events
+## Contributing
 
-It's compatible with all modern browsers that support these features.
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
 
 ## License
 
-MIT © [Christopher S. Aondona](https://codingsimba.com)
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "use-page-view",
-  "version": "1.0.0",
-  "description": "React hook for tracking page views",
+  "version": "1.0.1",
+  "description": "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.",
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -9,8 +9,19 @@
   ],
   "keywords": [
     "react",
+    "hooks",
     "page-view",
-    "typescript"
+    "analytics",
+    "tracking",
+    "engagement",
+    "time-tracking",
+    "localstorage",
+    "persistence",
+    "typescript",
+    "react-hooks",
+    "user-activity",
+    "page-visibility",
+    "performance-monitoring"
   ],
   "author": "Christopher S. Aondona <me@codingsimba.com> (https://codingsimba.com)",
   "repository": {
@@ -23,16 +34,17 @@
   },
   "scripts": {
     "build": "tsdown",
-    "test:watch": "vitest",
     "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "lint": "tsc",
     "format": "prettier --write .",
     "format:check": "prettier . --check",
     "exports:check": "attw --pack . --ignore-rules=cjs-resolves-to-esm",
     "release:version": "changeset version",
-    "release:local": "changeset version && changeset publish",
+    "release:local": "changeset && changeset version && changeset publish",
     "prepublishOnly": "npm run ci",
-    "ci": "npm run build && npm run format:check && npm run lint && npm run test"
+    "ci": "npm run build && npm run format:check && npm run lint && npm run exports:check && npm run test"
   },
   "license": "MIT",
   "dependencies": {
@@ -48,6 +60,7 @@
     "@types/react-dom": "^19.1.0",
     "@vitejs/plugin-react": "^4.5.1",
     "@vitest/browser": "^3.2.0",
+    "@vitest/coverage-v8": "^3.2.2",
     "playwright": "^1.52.0",
     "prettier": "^3.5.3",
     "tsdown": "^0.12.6",