0.1.3 • Published 7 months ago

overcentric v0.1.3

Weekly downloads
-
License
MIT
Repository
github
Last release
7 months ago

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 NameDescriptionProperties
$page_viewTriggered when a page is viewedurl, title, referrer
$errorTriggered when an uncaught JavaScript error occurserror_message, error_stack
$clickTriggered when an element is clickedelement_id, element_tag, element_class, element_text
$form_submitTriggered when a form is submittedform_id, form_name, form_action
$scrollTriggered when user scrollsscroll_percentage, scroll_position
$input_focusTriggered when an input receives focusinput_id, input_name, input_type
$page_visibleTriggered when page becomes visibletime_hidden
$page_hiddenTriggered when page becomes hiddentime_visible
$initial_visitTriggered on user's first visitinitial_referrer, initial_landing_page, utm_parameters
$identifyTriggered when a user is identifieduser_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

analyticstrackingeventsprivacyweb-analyticsuser-behavior
@rrweb/recorduuid
0.1.3

7 months ago

0.1.2

7 months ago

0.1.1

8 months ago

0.1.0

8 months ago

0.0.903

8 months ago

0.0.901

8 months ago

0.0.900

8 months ago

0.0.821

8 months ago

0.0.820

8 months ago

0.0.812

8 months ago

0.0.811

8 months ago

0.0.803

8 months ago

0.0.802

8 months ago

0.0.801

8 months ago

0.0.800

8 months ago

0.0.799

8 months ago

0.0.798

8 months ago

0.0.797

8 months ago

0.0.796

8 months ago

0.0.795

8 months ago

0.0.794

8 months ago

0.0.793

8 months ago

0.0.791

8 months ago

0.0.79

8 months ago

0.0.78

8 months ago

0.0.77

8 months ago

0.0.76

8 months ago

0.0.75

8 months ago

0.0.74

8 months ago

0.0.73

8 months ago

0.0.72

9 months ago

0.0.71

9 months ago

0.0.70

9 months ago

0.0.68

9 months ago

0.0.67

9 months ago

0.0.66

10 months ago

0.0.65

10 months ago

0.0.64

10 months ago

0.0.63

10 months ago

0.0.62

10 months ago

0.0.61

10 months ago

0.0.60

10 months ago

0.0.59

10 months ago

0.0.58

10 months ago

0.0.57

10 months ago

0.0.56

10 months ago

0.0.55

10 months ago

0.0.54

10 months ago

0.0.53

10 months ago

0.0.52

10 months ago

0.0.51

10 months ago

0.0.5

10 months ago

0.0.491

10 months ago

0.0.49

10 months ago

0.0.48

10 months ago

0.0.47

10 months ago

0.0.46

10 months ago

0.0.45

10 months ago

0.0.44

10 months ago

0.0.43

10 months ago

0.0.42

10 months ago

0.0.41

10 months ago

0.0.4

10 months ago

0.0.31

10 months ago

0.0.3

11 months ago

0.0.2

11 months ago

0.0.1

11 months ago