visionify-analytics-tracker/README.md

Track user session and page usage in apps

# React Page Usage Tracker

A lightweight and configurable React hook to track **user session time** and **page-level engagement** in applications.

---


## Installation

```bash
npm install visionify-analytics-tracker
```

---


## Usage

```tsx
import { useUsageTracker } from 'visionify-analytics-tracker';

useUsageTracker({
  trackablePaths: ['page_1', 'page_2', 'page_3'],
  pathMapping: {
    '/page_1': 'Page 1',
    '/page_2': 'Page 2',
    '/page_3': 'Page 3',
  },
  endpoint: '/api/test',            // Your API endpoint to receive events
  devMode: false,                    // Optional, Logs events to console instead of calling the API
  batchIntervalMs: 5 * 60 * 1000     // Optional, defaults to 5 minutes
  inactivityTimeoutMs: 30 * 60 * 1000 //Optional, defaults to 5 minutes
});
```

>  Call this hook once in your root component to start tracking.

---


##  Features

- Tracks time spent on specific pages
-  Stores data in local storage and sends it in regular intervals
-  Handles tab switches, focus loss, and page unloads
-  Prevents data loss using localStorage and `sendBeacon`
-  Dev mode support for local testing

---


##  API Reference

| Option           | Type                     | Description |
|------------------|--------------------------|-------------|
| `trackablePaths` | `string[]`               | List of page identifiers you want to track |
| `pathMapping`    | `Record<string,string>`  | Maps actual URL paths to logical page names |
| `endpoint`       | `string`                 | Your backend endpoint to receive batched events |
| `devMode`        | `boolean`                | Logs output to console without sending API calls |
| `batchIntervalMs`| `number`                 | Interval for batching events in milliseconds (default: 300000) |
| `inactivityTimeoutMs`| `number`                 | Interval for inactivity in milliseconds (default: 300000) |

---