overcentric v0.1.3
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
npm install overcentric
# or
yarn add overcentric
Browser
<script src="https://unpkg.com/overcentric/dist/browser/overcentric.min.js"></script>
Usage
In Node.js/React/Vue
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
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
<script src="https://unpkg.com/overcentric/dist/browser/overcentric.min.js"></script>
<script>
// Initialize overcentric
window.overcentric.init('your-project-id', {
debugMode: true,
enableAutoCapture: true,
});
// Identify a user
window.overcentric.identify('user123', {
name: 'John Doe',
email: 'john@example.com'
});
</script>
</head>
<body>
<!-- Your content here -->
</body>
</html>
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
overcentric.init('your-project-id');
<script
src="https://unpkg.com/overcentric/dist/browser/overcentric.min.js"
data-project-id="your-project-id">
</script>
All events will automatically include the current hostname, allowing you to analyze user behavior across different parts of your application.
Configuration Options
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:
{
"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:
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
7 months ago
7 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago