@sophonz/browser-sdk

Browser-side OpenTelemetry SDK for real user monitoring (RUM) and session replay.

Part of the Sophonz OpenTelemetry suite.

Install

bun add @sophonz/browser-sdk
# or
pnpm add @sophonz/browser-sdk
# or
npm install @sophonz/browser-sdk

CDN Usage

The SDK is available on the Sophonz CDN in three formats. Replace latest with a pinned version (e.g. 0.0.3) for immutable cache.

UMD (default, for <script> tags):

<script src="https://cdn.sophonz.com/release/npm/@browser-sdk/latest/index.js"></script>
<script>
  Sophonz.init({
    collectorUrl: 'https://your-collector.example.com',
    serviceName: 'my-app',
    serviceKey: 'your-api-key',
    serviceVersion: '1.0.0'
  });
</script>

ES Module:

<script type="module">
  import Sophonz from 'https://cdn.sophonz.com/release/npm/@browser-sdk/latest/index.mjs';
  Sophonz.init({ /* ... */ });
</script>

Legacy browsers (IE11):

<script src="https://cdn.sophonz.com/release/npm/@browser-sdk/latest/index-legacy.js"></script>

NPM/Bundler Usage

import Sophonz from '@sophonz/browser-sdk';

Sophonz.init({
  collectorUrl: 'https://your-collector.example.com',
  serviceName: 'my-app',
  serviceKey: 'your-api-key',
  serviceVersion: '1.0.0',
  deploymentEnvironment: 'production',
  webVitals: true,
  consoleCapture: true
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | collectorUrl | string | required | OTLP collector endpoint URL | | serviceName | string | required | Application name for identification | | serviceKey | string | required | Sophonz service API key | | serviceVersion | string | required | Application semantic version | | serviceNamespace | string | - | Optional service namespace | | deploymentEnvironment | string | - | Environment name (e.g., production, staging) | | authorizationToken | string | - | Authentication token for OTLP | | samplingProbability | number | string | 1 | Trace sampling rate (0-1) | | webVitals | boolean | true | Capture Web Vitals (LCP, FID, CLS) | | consoleCapture | boolean | false | Capture console.log/warn/error | | disableReplay | boolean | true | Enable session replay recording | | maskAllInputs | boolean | true | Mask input values in replay | | maskAllText | boolean | false | Mask all text in replay | | recordCanvas | boolean | false | Record canvas element changes | | websocket | boolean | false | Capture WebSocket connections | | socketio | boolean | false | Capture Socket.IO events | | userJourney | boolean | false | Track user navigation journey | | captureMetrics | boolean | false | Collect custom metrics | | opampServerUrl | string | - | OpAMP server for dynamic config | | exporterProtocol | 'proto' | 'json' | 'json' | OTLP protocol format | | sessionStorage | 'cookie' | 'localStorage' | 'cookie' | Session ID storage method | | tracePropagationTargets | (string | RegExp)[] | - | Domains for trace header propagation |

Peer Dependencies

None.

License

See LICENSE in this package.

Part of sophonz-js.