overcentric

v1.1.85

Published

a month ago

A lightweight, privacy-focused toolkit for modern SaaS web applications

Downloads

729

0High
0Medium
0Low

overcentric

analytics tracking events privacy web-analytics user-behavior

Overcentric

A lightweight, privacy-focused toolkit for modern SaaS web applications. Overcentric helps you understand acquisition, usage and support your users through automatic event tracking, pre-built analytics reports, session replays, chat support, help center 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
Session Replay: Records user session replays for debugging and support.
Chat Support: Chat support widget.
Help Center: Help Center (Knowledge Base) widget.

Installation

NPM

npm install overcentric
# or
yarn add overcentric

Browser

<script
  defer
  src="https://unpkg.com/overcentric/dist/browser/overcentric.min.js"
  data-project-id="your-project-id"
></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: "[email protected]",
});

// Track custom event
overcentric.trackEvent("button_clicked", {
  buttonId: "signup-button",
});

In Browser

<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
    <script
      defer
      src="https://unpkg.com/overcentric/dist/browser/overcentric.min.js"
      data-project-id="your-project-id"
    ></script>
    <script>
      // Wait for the library to load before calling methods
      window.addEventListener("load", function () {
        window.overcentric.default.identify("user123", {
          name: "John Doe",
          email: "[email protected]",
        });
      });
    </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 |

Reserved Event Names

Apart from the events listed above, the following event names are reserved for tracking most common user actions. It is recommended to use these event names so you automatically get pre-built analytics reports.

$signup
$signin
$activate
$subscription_purchase
$subscription_upgrade
$subscription_downgrade
$subscription_cancel
$account_delete
$onboarding_start
$onboarding_complete

Naming Custom Events

You can track custom events using the trackEvent method.

overcentric.trackEvent("event_name", {
  property1: "value1",
  property2: "value2",
});

We recommend using snake_case for event names. The first part of the event name should be a description of the event, business or part of the UI, and the second part should be the action in simple present tense. Some examples:

cta_click
report_submit
chart_download
table_export

Context Tracking

Overcentric covers the full user journey, from acquisition to product usage and support. To help differentiate between different contexts, such as marketing website and product dashboard, you should use the context parameter.

The context parameter can be set to one of the following values:

website (your marketing website, ie. landing page, e.g. https://www.overcentric.com)
product (your product dashboard, e.g. https://app.overcentric.com)

Below are the examples of how to use the context parameter.

<script
  src="https://unpkg.com/overcentric/dist/browser/overcentric.min.js"
  data-project-id="your-project-id"
  data-context="website"
></script>

overcentric.init("your-project-id", {
  context: "product",
});

Configuration Options

Your Overcentric integration can be easily configured in Overcentric dashboard, on the Settings tab on the Project page (https://app.overcentric.com/projects/{your-project-id}).

If you prefer to configure your Overcentric integration manually, you can use the following options. Manually configured options will override the ones set in the dashboard.

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 session replay recording
  enableRecording: false,

  // Enable chat support
  enableChat: false,

  // Enable Help Center (knowledge base) support
  enableKB: 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: "[email protected]", // 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)

Signup Tracking

To track signup events, use the trackEvent method with the $signup event name with optional properties:

overcentric.trackEvent("$signup", {
  method: "email",
  plan: "trial",
});

Purchase Tracking

To track purchase events, use the trackEvent method with the $purchase event name with optional properties:

overcentric.trackEvent("$purchase", {
  plan: "growth",
});

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.

Usage in Different Environments

You can use Overcentric in different environments such as local development, staging and production. To do so, each environment should have its own project ID. A new project can be created from the Overcentric dashboard.

License

MIT