0.1.3 • Published 3 months ago

overcentric v0.1.3

Weekly downloads
-
License
MIT
Repository
github
Last release
3 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

3 months ago

0.1.2

3 months ago

0.1.1

3 months ago

0.1.0

3 months ago

0.0.903

4 months ago

0.0.901

4 months ago

0.0.900

4 months ago

0.0.821

4 months ago

0.0.820

4 months ago

0.0.812

4 months ago

0.0.811

4 months ago

0.0.803

4 months ago

0.0.802

4 months ago

0.0.801

4 months ago

0.0.800

4 months ago

0.0.799

4 months ago

0.0.798

4 months ago

0.0.797

4 months ago

0.0.796

4 months ago

0.0.795

4 months ago

0.0.794

4 months ago

0.0.793

4 months ago

0.0.791

4 months ago

0.0.79

4 months ago

0.0.78

4 months ago

0.0.77

4 months ago

0.0.76

4 months ago

0.0.75

4 months ago

0.0.74

4 months ago

0.0.73

4 months ago

0.0.72

5 months ago

0.0.71

5 months ago

0.0.70

5 months ago

0.0.68

5 months ago

0.0.67

5 months ago

0.0.66

5 months ago

0.0.65

5 months ago

0.0.64

5 months ago

0.0.63

5 months ago

0.0.62

5 months ago

0.0.61

6 months ago

0.0.60

6 months ago

0.0.59

6 months ago

0.0.58

6 months ago

0.0.57

6 months ago

0.0.56

6 months ago

0.0.55

6 months ago

0.0.54

6 months ago

0.0.53

6 months ago

0.0.52

6 months ago

0.0.51

6 months ago

0.0.5

6 months ago

0.0.491

6 months ago

0.0.49

6 months ago

0.0.48

6 months ago

0.0.47

6 months ago

0.0.46

6 months ago

0.0.45

6 months ago

0.0.44

6 months ago

0.0.43

6 months ago

0.0.42

6 months ago

0.0.41

6 months ago

0.0.4

6 months ago

0.0.31

6 months ago

0.0.3

6 months ago

0.0.2

6 months ago

0.0.1

6 months ago