Open SDK Analytics (Vendor-Neutral, Zero-Lock-in)

Builder: Sohan Ananthula

An open-source, vendor-neutral alternative to @enter-pro/analytics-sdk. Zero runtime dependencies, resilient offline queueing, automatic SPA page tracking, Web Vitals, active session timing, declarative DOM click/submit tracking, and user identity resolution (identify).

Why Open SDK Analytics?

The @enter-pro/analytics-sdk has several critical vendor locks:

1. Hardcoded Proprietary Backend: Pointed by default to https://api.enter.pro/code/api/v1/track.
2. Server-Side Event Registration Barrier: If you call trackEvent('button_clicked') without first registering button_clicked with Enter's proprietary backend API (POST /v1/projects/:pid/analytics/events/registry), Enter's server rejects the events with rejected.reason: "event not registered".
3. No User Identity Tracking: The original Enter SDK has no identify(userId, traits) method.
4. Hardcoded Namespaces: Enter-specific keys (enter.analytics.visitor_id, VITE_ENTER_*).

Open SDK Analytics removes all these restrictions:

• Send events to any endpoint: your own backend, a webhook, ClickHouse, Supabase, PostHog, or the included self-hosted receiver.
• Track any event freely without pre-registering it with an external proprietary API.
• Full identify(userId, traits) and resetIdentity() support.
• 100% Drop-in backward compatibility with @enter-pro/analytics-sdk (same exports and function signatures).

Quick Start

1. Installation

npm install open-sdk-analytics

2. Modern API

import { initAnalytics, track, identify } from 'open-sdk-analytics';

// Initialize at app entry
initAnalytics({
  endpoint: 'https://analytics.yourdomain.com/api/v1/track', // or '/api/track'
  appId: 'my-project',
  debug: true
});

// Track custom events freely
track('pricing_viewed', {
  properties: { plan: 'pro', billing: 'annual' }
});

// Identify logged-in users
identify('usr_98765', {
  traits: { email: '[email protected]', tier: 'enterprise' }
});

3. Drop-in Replacement for @enter-pro/analytics-sdk

If you are migrating existing code that used @enter-pro/analytics-sdk:

- import { bootstrapEnterAnalytics, trackEvent } from '@enter-pro/analytics-sdk';
+ import { bootstrapEnterAnalytics, trackEvent } from 'open-sdk-analytics';

bootstrapEnterAnalytics();
trackEvent('button_click', { properties: { cta: 'hero' } });

Features

• Automatic SPA Route Tracking: Listens to pushState, replaceState, popstate, and optional hash routing.
• Accurate Active Session Duration: Tracks actual visible tab time (time_on_page_ms), pauses when tab is hidden.
• Web Vitals & Performance: Native PerformanceObserver fallbacks for LCP, FCP, CLS, TTFB, and DOMContentLoaded.
• Error & Rejection Capture: Automatic error listener with third-party marketing noise filtering.
• Declarative DOM Event Listeners: Attach tracking to CSS selectors (click, submit) with automatic property extraction (attribute, dataset, formField, etc.).
• Offline Resilient Outbox: Queues events in localStorage, batches up to 20 events, flushes on interval, handles exponential jittered retries, and sends keepalive beacons on page exit.

Self-Hosting the Ingestion Backend

A lightweight, zero-dependency ingestion server is included in server/ingest.js.

node server/ingest.js

It accepts incoming POST requests at /api/v1/track and appends verified events directly to events.jsonl (or your chosen database).