# overcentric
A lightweight, privacy-focused toolkit for modern web applications. overcentric helps you understand how users interact with your application through automatic event tracking, custom analytics and more.
## Features
- **Automatic Event Tracking**: Captures page views, clicks, form submissions, and more
- **Privacy-Focused**: Collects only what matters, respecting user privacy
- **Lightweight**: Minimal impact on your application's performance
- **Custom Events**: Track any custom events that matter to your business
- **SPA Support**: Built-in support for Single Page Applications
- **UTM Tracking**: Automatic UTM parameter tracking for marketing campaigns
- **User Identification**: Associate events with specific users
- **Attribution Tracking**: Capture initial referrer and UTM parameters
- **Error Tracking**: Automatically capture JavaScript errors
- **Session Tracking**: Automatically tracks user sessions with intelligent timeout handling:
- Sessions expire after 30 minutes of inactivity
- New sessions start when users return after being away from the application for more than 10 minutes
## Installation
### NPM
```bash
npm install overcentric
# or
yarn add overcentric
```
### Browser
```html
```
## Usage
### In Node.js/React/Vue
```javascript
import overcentric from 'overcentric';
// Initialize with your project ID
overcentric.init('your-project-id');
// Initialize with your project ID and configuration
overcentric.init('your-project-id', {
debugMode: true,
enableAutoCapture: true,
});
// Identify a user
overcentric.identify('user123', {
name: 'John Doe',
email: 'john@example.com'
});
// Track custom event
overcentric.trackEvent('button_clicked', {
buttonId: 'signup-button'
});
```
### In Browser
```html
My Website
```
## Auto-Captured Events
| Event Name | Description | Properties |
|------------|-------------|------------|
| `$page_view` | Triggered when a page is viewed | `url`, `title`, `referrer` |
| `$error` | Triggered when an uncaught JavaScript error occurs | `error_message`, `error_stack` |
| `$click` | Triggered when an element is clicked | `element_id`, `element_tag`, `element_class`, `element_text` |
| `$form_submit` | Triggered when a form is submitted | `form_id`, `form_name`, `form_action` |
| `$scroll` | Triggered when user scrolls | `scroll_percentage`, `scroll_position` |
| `$input_focus` | Triggered when an input receives focus | `input_id`, `input_name`, `input_type` |
| `$page_visible` | Triggered when page becomes visible | `time_hidden` |
| `$page_hidden` | Triggered when page becomes hidden | `time_visible` |
| `$initial_visit` | Triggered on user's first visit | `initial_referrer`, `initial_landing_page`, `utm_parameters` |
| `$identify` | Triggered when a user is identified | `user_id`, `name`, `email` |
## Context Tracking
```javascript
overcentric.init('your-project-id');
```
```html
```
All events will automatically include the current hostname, allowing you to analyze user behavior across different parts of your application.
## Configuration Options
```javascript
overcentric.init('your-project-id', {
// Enable debug logging
debugMode: true,
// Enable automatic event capturing
enableAutoCapture: true,
// Configure which events to auto-capture
autoCaptureConfig: {
click: true,
scroll: true,
formSubmit: true,
inputFocus: true,
visibilityChange: true
},
// Enable error tracking
enableErrorCapture: true,
// Enable dock interface (optional)
enableDock: false,
// Custom API basepath (optional, defaults to https://app.overcentric.com/api)
basePath: 'https://your-api.com/api'
});
```
## Event Data Structure
When events are sent to the server, they include the following information:
```javascript
{
"event": {
"name": "event_name",
"properties": {/* custom properties */},
"project_id": "your-project-id",
"device_id": "unique-device-id",
"session_id": "current-session-id",
"url": "current-page-url",
"referrer": "referrer-url" // if available
},
"identity": { // if user is identified
"unique_identifier": "user-id",
"email": "user-email", // if provided
"name": "user-name", // if provided
"project_id": "your-project-id"
}
}
```
## User Identification
The `identify` method allows you to associate events with specific users and attach additional user information:
```javascript
overcentric.identify('user123', {
name: 'John Doe', // optional
email: 'john@example.com' // optional
});
```
After calling `identify`, all subsequent events will include the user ID. The library also automatically:
- Generates and maintains a unique device ID
- Tracks the initial referrer and UTM parameters on first visit
- Associates all events with both device ID and user ID (when available)
## Attribution Tracking
overcentric automatically captures attribution data on the user's first visit:
- Initial referrer
- Landing page URL
- UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`)
- Timestamp of first visit
This data is stored locally and sent with the `$initial_visit` event, allowing you to understand where your users are coming from.
## License
MIT