Web SDK

1 Installation

npm

npm install @secureinspector/web-sdk

yarn

yarn add @secureinspector/web-sdk

pnpm

pnpm add @secureinspector/web-sdk

2 Initialization

Initialize the SDK as early as possible in your application:

import { secureInspector } from '@secureinspector/web-sdk';

// Initialize with encryption key
await secureInspector.initialize({
  serverURL: 'https://your-server.com',
  apiKey: 'your-api-key',
  encryptionKey: 'your-base64-encryption-key',
});

Using Password Instead of Key

You can use a password for automatic key derivation (PBKDF2):

// Password-based initialization
await secureInspector.initializeWithPassword({
  serverURL: 'https://your-server.com',
  apiKey: 'your-api-key',
  password: 'your-secure-password',
});

3 HTTP Capture

HTTP traffic is automatically captured by intercepting fetch and XMLHttpRequest. No additional setup required!

Captured automatically:

Request URL, method, headers, body
Response status, headers, body
Request duration
Error details (if failed)

Sensitive data is automatically masked (Authorization headers, tokens, passwords, etc.)

4 User Identification

Set the user ID after login to enable debug sessions:

// After successful login
secureInspector.setUserId('user@example.com');

// On logout
secureInspector.clearUserId();

Session Required

The SDK only captures data when a debug session is active in the dashboard AND the user ID matches.

5 Error Capture

Errors are automatically captured (window.onerror, unhandledrejection). You can also manually capture errors:

try {
  riskyOperation();
} catch (error) {
  secureInspector.captureError(error, {
    orderId: '12345',
    action: 'checkout'
  });
}

6 Custom Events

Track custom events with properties:

secureInspector.captureEvent(
  'purchase_completed',
  {
    productId: 'SKU123',
    price: 99.99,
    currency: 'EUR'
  },
  'info'  // level: 'debug' | 'info' | 'warning' | 'error'
);

7 Console Capture

Optionally capture console.log, console.warn, and console.error:

await secureInspector.initialize({
  serverURL: 'https://your-server.com',
  apiKey: 'your-api-key',
  encryptionKey: 'your-encryption-key',

  // Enable console capture
  captureConsole: true,
  consoleLevels: ['warn', 'error'],  // Which levels to capture
});

8 Configuration Options

await secureInspector.initialize({
  // Required
  serverURL: 'https://your-server.com',
  apiKey: 'your-api-key',
  encryptionKey: 'your-encryption-key',

  // Session polling interval (ms)
  sessionCheckInterval: 30000,

  // Max request/response body size to capture
  maxBodySize: 1024 * 1024,  // 1MB

  // URL patterns to exclude (regex strings)
  excludeURLPatterns: [
    '.*analytics.*',
    '.*tracking.*',
    '.*hotjar.*'
  ],

  // Custom sensitive headers to mask
  sensitiveHeaders: ['X-Custom-Auth'],

  // Custom sensitive fields to mask
  sensitiveFields: ['ssn', 'taxId'],

  // Feature toggles
  captureHTTP: true,
  captureErrors: true,
  captureEvents: true,
  captureConsole: false,

  // Debug mode (logs to console)
  debugMode: false,

  // Error callback
  onError: (error) => {
    console.error('SecureInspector error:', error);
  }
});

9 React Integration

Initialize in your app entry point:

// main.tsx or index.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { secureInspector } from '@secureinspector/web-sdk';
import App from './App';

// Initialize before rendering
secureInspector.initialize({
  serverURL: import.meta.env.VITE_INSPECTOR_URL,
  apiKey: import.meta.env.VITE_INSPECTOR_API_KEY,
  encryptionKey: import.meta.env.VITE_INSPECTOR_KEY,
}).then(() => {
  ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
      <App />
    </React.StrictMode>
  );
});

Error Boundary Integration

import { secureInspector } from '@secureinspector/web-sdk';

class ErrorBoundary extends React.Component {
  componentDidCatch(error, errorInfo) {
    secureInspector.captureError(error, {
      componentStack: errorInfo.componentStack
    });
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallback />;
    }
    return this.props.children;
  }
}

10 Vue Integration

Initialize in your app entry point:

// main.ts
import { createApp } from 'vue';
import { secureInspector } from '@secureinspector/web-sdk';
import App from './App.vue';

const app = createApp(App);

// Initialize SDK
secureInspector.initialize({
  serverURL: import.meta.env.VITE_INSPECTOR_URL,
  apiKey: import.meta.env.VITE_INSPECTOR_API_KEY,
  encryptionKey: import.meta.env.VITE_INSPECTOR_KEY,
});

// Global error handler
app.config.errorHandler = (error, instance, info) => {
  secureInspector.captureError(error as Error, {
    component: instance?.$options.name,
    info
  });
};

app.mount('#app');

11 TypeScript

The SDK is written in TypeScript and includes full type definitions:

import {
  SecureInspector,
  SecureInspectorConfig,
  EventLevel,
  SessionState
} from '@secureinspector/web-sdk';

const config: SecureInspectorConfig = {
  serverURL: 'https://your-server.com',
  apiKey: 'your-api-key',
  encryptionKey: 'your-encryption-key',
};

const session: SessionState | null = secureInspector.getSession();

secureInspector.captureEvent(
  'event_name',
  { key: 'value' },
  'info' as EventLevel
);

API Reference

secureInspector.initialize(config)

Initialize the SDK with configuration. Returns a Promise.

secureInspector.initializeWithPassword(config)

Initialize with password-based key derivation (PBKDF2).

secureInspector.setUserId(userId)

Set current user ID. Required for session matching.

secureInspector.clearUserId()

Clear user ID (call on logout).

secureInspector.captureError(error, context?, isFatal?)

Manually capture an error with optional context.

secureInspector.captureEvent(name, properties?, level?)

Capture a custom event with optional properties.

secureInspector.getSession()

Get current session state or null.

secureInspector.isReady()

Check if SDK is initialized.

secureInspector.getDeviceId()

Get the device/browser identifier.

secureInspector.shutdown()

Shutdown the SDK and release resources. Returns a Promise.

Browser Support

Supported Browsers

Chrome 80+
Firefox 75+
Safari 13.1+
Edge 80+

Requirements

WebCrypto API (for encryption)
IndexedDB (for local storage)
Fetch API