WebYes RUM SDK

Lightweight, privacy-safe Real User Monitoring SDK built with TypeScript and web-vitals.

Overview

The WebYes RUM SDK is a lightweight, privacy-first solution for monitoring real user experiences on web applications. It tracks Core Web Vitals, user interactions, and errors while maintaining strict privacy standards.

Features

• Privacy-First: No personally identifiable information (PII) collected
• Lightweight: Minimal bundle size for fast loading
• Event-Driven: Sends data only on page reloads/navigation (not continuous polling)
• Performance Monitoring: Tracks Core Web Vitals (CLS, FID, INP, LCP, FCP, TTFB)
• Error Tracking: Captures JavaScript errors and unhandled promise rejections
• User Journey: Tracks page views and navigation events
• Safe Attribution: Element selectors without exposing text content

Quick Start

Installation

# Clone the repository
git clone [email protected]:webyes-apps/rum-client-sdk.git
cd rum-client-sdk

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Serve demo locally
npm run serve

CDN Usage (Production)

<script src="https://cdn.example.com/rum-sdk.min.js"></script>
<script>
  WebYesRUM.init({
    endpoint: 'https://your-rum-endpoint.com/collect',
    apiKey: 'your-api-key',
    sampleRate: 1.0,
    debug: false
  });
</script>

NPM Usage

import WebYesRUM from 'webyes-rum-sdk';

WebYesRUM.init({
  endpoint: 'https://your-rum-endpoint.com/collect',
  apiKey: 'your-api-key',
  sampleRate: 1.0,
  debug: false
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | endpoint | string | - | Required. URL where RUM data will be sent | | apiKey | string | - | Required. API key for authentication | | sampleRate | number | 1.0 | Sampling rate (0.0 to 1.0) | | debug | boolean | false | Enable debug logging | | userId | string | null | Optional user identifier | | sessionId | string | Auto-generated | Session identifier | | environment | string | 'production' | Environment name |

API Reference

WebYesRUM.init(config)

Initialize the RUM SDK with configuration.

WebYesRUM.trackEvent(name, data)

Manually track custom events.

WebYesRUM.trackEvent('user_action', {
  action: 'button_click',
  element: 'cta-button'
});

WebYesRUM.setUserContext(userData)

Set user context information.

WebYesRUM.setUserContext({
  userId: '12345',
  plan: 'premium'
});

Data Transmission

The SDK sends data only on page reload/navigation events:

• Page Load: When the page first loads
• Page Navigation: When the user navigates away from the page

Unlike traditional RUM solutions that send data every 30 seconds, this approach:

• Reduces server load and costs
• Minimizes client-side processing
• Sends data only when meaningful events occur

Development

Prerequisites

• Node.js 16+
• npm or yarn

Available Scripts

• npm run dev - Development build with watch mode
• npm run build - Production build with minification
• npm run serve - Serve demo files locally

Project Structure

src/
├── rum-sdk.ts          # Main SDK implementation
demo/
├── index.html          # Basic demo
└── index2.html         # Advanced demo
dist/
├── rum-sdk.min.js      # Production bundle
└── rum-sdk.global.js.map  # Source map

Browser Support

• Chrome 77+
• Firefox 78+
• Safari 14+
• Edge 79+

Data Collection

Performance Metrics

• CLS (Cumulative Layout Shift)
• FID (First Input Delay)
• INP (Interaction to Next Paint)
• LCP (Largest Contentful Paint)
• FCP (First Contentful Paint)
• TTFB (Time to First Byte)

User Journey

• Page views
• Navigation events
• User interactions

Error Tracking

• JavaScript errors
• Unhandled promise rejections
• Network failures

Privacy & Security

• No PII Collection: SDK does not collect personally identifiable information
• Safe Selectors: Element attribution uses CSS selectors without exposing text content
• Minimal Data: Only essential performance and error data is collected
• HTTPS Only: All data transmission is encrypted
• Configurable Sampling: Control data collection volume

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test your changes
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Add tests for new features
• Update documentation as needed
• Ensure code passes linting

License

MIT License - see LICENSE file for details.

Support

For support and questions:

• Create an issue in this repository
• Contact the WebYes development team