JSClient SDK

Real User Monitoring SDK - TypeScript client library with API key validation

Installation

npm install RUM-CLIENT

RUM SDK — JSClient-SDK

A lightweight Real User Monitoring (RUM) client library (TypeScript). This README summarizes the features implemented so far, integration examples, build notes, and suggested next steps.

What this repo contains

• Source: index.ts
• Implemented SDK features:
  • API Key Validation: validates the provided apiKey against the backend /api/validate-key during SDK construction.
  • Device ID: generates and persists deviceId in localStorage (rum_device_id).
  • User & Session IDs: userId persisted in localStorage (rum_user_id); sessionId persisted for the browser session (sessionStorage rum_session_id).
  • Tracking Methods: getDeviceId(), trackPageView(), trackEvent(), trackError() — safe to call after onReady.
  • Send to Backend: posts events to /v1/track using navigator.sendBeacon when possible, falling back to fetch.
  • Batching & Periodic Flush: in-memory queue with configurable batch size (default 5) and periodic flush (default 5s).
  • Offline Queue (localStorage fallback): failed batches are saved to localStorage under rum_offline_queue and retried on init or via processOfflineQueue().

Key file

• index.ts — main SDK implementation (TypeScript). See the RUM class for public API and configuration.

Usage — React (recommended)

• Initialize once (root of app) and use onReady before calling tracking methods because validation is asynchronous.

Example (React + TypeScript):

import React, { useEffect, useRef } from 'react';
import RUM from './dist/index.js'; // or from your built package

export default function App() {
  const rumRef = useRef<RUM | null>(null);

  useEffect(() => {
    rumRef.current = new RUM({
      apiKey: 'REPLACE_WITH_YOUR_KEY',
      onReady: () => {
        console.log('RUM ready', rumRef.current?.getDeviceId());
        rumRef.current?.trackPageView();
      },
      onError: (err) => console.error('RUM error', err)
    });
  }, []);

  return <div>App content</div>;
}

Usage — Plain JS (script tag)

• If you build a UMD bundle or attach RUM to window, use:

<script src="/path/to/rum.bundle.js"></script>
<script>
  const rum = new window.RUM({
    apiKey: 'REPLACE_WITH_YOUR_KEY',
    onReady() {
      console.log('deviceId', rum.getDeviceId());
      rum.trackPageView();
    },
    onError(err) { console.error(err); }
  });
</script>

Build / bundling (quick)

• The package is TypeScript source (index.ts). Minimal compile with tsc:

# install TypeScript locally if needed
npm install --save-dev typescript

# compile single file to `dist` (adjust `tsc` options as needed)
npx tsc index.ts --outDir dist --module ES2020 --target ES2017

• Or add a build script to package.json:

"scripts": {
  "build": "tsc"
}

and run npm run build.

Behaviour & notes

• The constructor validates the apiKey asynchronously; prefer onReady before tracking.
• All outgoing payloads include apiKey, deviceId, userId, and sessionId where applicable.
• The SDK queues events and sends batched payloads to /v1/track — failed batches are saved to the offline queue.
• Offline queue uses localStorage as the current fallback; consider IndexedDB for production reliability.

Next suggested improvements (I can implement)

• IndexedDB offline queue for larger/more reliable storage.
• Exponential backoff and retry for failed sends.
• Public flush() to force immediate send of queued events.
• Configurable batchSize, flushIntervalMs, and offline storage selection.
• Implement additional tracking features from the full reference (performance, network, session replay, breadcrumbs).

If you want, I can implement one of the improvements above (IndexedDB, retry/backoff, or a demo app). Tell me which and I'll proceed.