@pvyswiss/analytics-sdk

v2.0.2

Published

25 days ago

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

0High
0Medium
0Low

pvy.swiss

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

PVYanalytics 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 @pvyswiss/analytics-sdk
# or
pnpm add @pvyswiss/analytics-sdk

Quick Start

Vanilla JavaScript / React

import { initPVYanalytics } from "@pvyswiss/analytics-sdk";

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

Next.js

For Next.js applications, use the PVYanalyticsComponent:

import { PVYanalyticsComponent } from "@pvyswiss/analytics-sdk/nextjs";

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

Get your projectId and apiKey from your PVYanalytics Dashboard.

Configuration Options

`PVYanalyticsComponent` (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://ws.analytics.pvy.swiss 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

`initPVYanalytics(options)`

Required Parameters:

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

Optional Parameters:

wsHost (string) - WebSocket server URL. Defaults to wss://ws.analytics.pvy.swiss 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

initPVYanalytics({
  projectId: "your-project-id",
  apiKey: "your-api-key",
  wsHost: "wss://ws.analytics.pvy.swiss", // 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://ws.analytics.pvy.swiss 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 "@pvyswiss/analytics-sdk";

trackPageView();

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

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

import { trackEvent } from "@pvyswiss/analytics-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:

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

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

Architecture

Browser SDK → WebSocket (wss://ws.analytics.pvy.swiss) → 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 { initPVYanalytics } from "@pvyswiss/analytics-sdk";

initPVYanalytics({
  projectId: "your-project-id",
  apiKey: "your-api-key",
  apiHost: "https://analytics.pvy.swiss/api/track",  // ❌ No longer used
});

After (v1.0.0):

import { initPVYanalytics } from "@pvyswiss/analytics-sdk";

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

Or simplest (recommended):

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

For Next.js Apps

Before (v0.x):

<PVYanalyticsComponent
  projectId="..."
  apiKey="..."
  apiHost="https://analytics.pvy.swiss/api/track"  // ❌ Remove this
/>

After (v1.0.0):

<PVYanalyticsComponent
  projectId="..."
  apiKey="..."
  wsHost="wss://ws.analytics.pvy.swiss:8080"  // Optional - auto-detected
/>

Or simplest:

<PVYanalyticsComponent
  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