@bklit/sdk

v1.0.1

Published

3 months ago

A lightweight analytics SDK for tracking page views, sessions, and user behavior via WebSocket.

0High
0Medium
0Low

uixmat

analytics tracking page-views sessions web-analytics websocket real-time realtime-analytics bklit

Bklit Analytics SDK

A lightweight analytics SDK for tracking page views, sessions, and user behavior via WebSocket.

⚠️ Upgrading from v0.x? See the Migration Guide below.

Installation

npm install @bklit/sdk
# or
pnpm add @bklit/sdk

Quick Start

Vanilla JavaScript / React

import { initBklit } from "@bklit/sdk";

initBklit({
  projectId: "your-project-id",
  apiKey: "your-api-key",
  debug: true, // Optional - enables console logging
});

Next.js

For Next.js applications, use the BklitComponent:

import { BklitComponent } from "@bklit/sdk/nextjs";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <BklitComponent
          projectId="your-project-id"
          apiKey="your-api-key"
          debug={process.env.NODE_ENV === "development"}
        />
        {children}
      </body>
    </html>
  );
}

Get your projectId and apiKey from your Bklit Dashboard.

Configuration Options

`BklitComponent` (Next.js)

Props:

projectId (string, required) - Your unique project identifier
apiKey (string, optional) - Your API authentication token
wsHost (string, optional) - WebSocket server URL. Defaults to wss://bklit.ws in production, ws://localhost:8080 in development
environment (string, optional) - Environment mode: "development" or "production". Defaults to "production"
debug (boolean, optional) - Enable debug logging. Defaults to false

`initBklit(options)`

Required Parameters:

projectId (string) - Your unique project identifier from the Bklit dashboard
apiKey (string) - Your API authentication token from the Bklit dashboard

Optional Parameters:

wsHost (string) - WebSocket server URL. Defaults to wss://bklit.ws in production, ws://localhost:8080 in development
environment (string) - Set to "development" for local testing. Defaults to "production"
debug (boolean) - Enable detailed console logging. Defaults to false

Example with All Options

initBklit({
  projectId: "your-project-id",
  apiKey: "your-api-key",
  wsHost: "wss://bklit.ws", // Optional - auto-detected
  environment: "production", // Optional
  debug: false, // Optional
});

How It Works

The SDK establishes a WebSocket connection to track analytics in real-time:

Persistent Connection - Opens WebSocket to wss://bklit.ws on initialization
Automatic Tracking - Sends pageviews and navigation events over WebSocket
Instant Session End - Sessions end automatically when the browser tab closes (WebSocket disconnect)
Auto-Reconnect - Reconnects automatically with exponential backoff if connection drops
Message Queuing - Queues events when connection is not ready

API Reference

`trackPageView()`

Manually track a page view. Usually not needed as the SDK auto-tracks navigation.

import { trackPageView } from "@bklit/sdk";

trackPageView();

`trackEvent(trackingId, eventType, metadata, triggerMethod)`

Track custom events like button clicks, form submissions, etc.

import { trackEvent } from "@bklit/sdk";

trackEvent(
  "cta-button", // tracking ID
  "click", // event type
  { buttonText: "Sign Up", position: "hero" }, // metadata (optional)
  "automatic" // trigger method (optional)
);

Console Logging

When debug: true is enabled, the SDK provides detailed console logs:

🔌 Bklit SDK: Connecting to WebSocket
✅ Bklit SDK: WebSocket connected
🚀 Bklit SDK: Message sent via WebSocket
📦 Bklit SDK: Message queued (WebSocket not ready)
🔄 Bklit SDK: Reconnecting...

Error messages (using console.error and console.warn) always appear regardless of the debug setting.

Architecture

Browser SDK → WebSocket (wss://bklit.ws) → Queue → ClickHouse
     ↓                                         ↓
Auto-reconnect                          Real-time Dashboard

Sub-second latency for real-time analytics
Instant session tracking - Sessions appear/disappear immediately
Reliable - Browser handles WebSocket cleanup automatically

Migrating from v0.x

Breaking Changes in v1.0.0

v1.0.0 migrates from HTTP to WebSocket architecture. This requires a configuration change:

Before (v0.x):

import { initBklit } from "@bklit/sdk";

initBklit({
  projectId: "your-project-id",
  apiKey: "your-api-key",
  apiHost: "https://app.bklit.com/api/track",  // ❌ No longer used
});

After (v1.0.0):

import { initBklit } from "@bklit/sdk";

initBklit({
  projectId: "your-project-id",
  apiKey: "your-api-key",
  wsHost: "wss://bklit.ws:8080",  // Optional - auto-detected in most cases
});

Or simplest (recommended):

initBklit({
  projectId: "your-project-id",
  apiKey: "your-api-key",
  // wsHost auto-detected based on environment
});

For Next.js Apps

Before (v0.x):

<BklitComponent
  projectId="..."
  apiKey="..."
  apiHost="https://app.bklit.com/api/track"  // ❌ Remove this
/>

After (v1.0.0):

<BklitComponent
  projectId="..."
  apiKey="..."
  wsHost="wss://bklit.ws:8080"  // Optional - auto-detected
/>

Or simplest:

<BklitComponent
  projectId="..."
  apiKey="..."
  // wsHost auto-detected
/>

What Changed

✅ HTTP → WebSocket: Persistent connection instead of HTTP requests
✅ Instant session ending: <1 second instead of 30s-4min
✅ Auto-reconnection: Handles network issues gracefully
✅ Removed: endSession() function (automatic now)

Need Help?

See the full CHANGELOG or open an issue.

License

MIT