@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',
    project: 'my-project',
    appName: 'my-app',
    appVersion: '1.0.0',
    appKey: 'your-api-key'
  });
</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',
  project: 'my-project',
  appName: 'my-app',
  appVersion: '1.0.0',
  appKey: 'your-api-key',
  deploymentEnvironment: 'production',
  webVitals: true,
  consoleCapture: true
});

Configuration

| Option | Type | Default | Description | | ------------------------- | -------------------------- | -------- | -------------------------------------------- | | collectorUrl | string | required | OTLP collector endpoint URL | | project | string | - | Project the app belongs to; sets service.namespace. App names are expected to be unique within a project | | appName | string | required | Application name; sets service.name | | appVersion | string | required | Application semantic version; sets service.version | | appKey | string | required | Sophonz ingestion key; sets service.key. Publicly visible, so never put an access token here | | deploymentEnvironment | string | - | Environment name (e.g., production, staging) | | authorizationToken | string | - | Authentication token for OTLP | | defaultAttributes | Attributes | - | Default resource attributes | | samplingProbability | number | string | 1 | Session sampling rate (0-1) | | webVitals | boolean | true | Capture Web Vitals (LCP, CLS, FCP, TTFB, INP) | | consoleCapture | boolean | false | Capture console.log/warn/error | | advancedNetworkCapture | boolean | false | Capture request and response detail on network spans | | debug | boolean | false | Verbose logging | | disableReplay | boolean | true | Disable session replay. Replay is off unless you set this to false | | maskAllInputs | boolean | true | Mask input values in replay | | maskAllText | boolean | false | Mask all text in replay | | maskClass | string | - | Class whose text is masked in replay | | blockClass | string | - | Class blocked from replay entirely | | ignoreClass | string | - | Class ignored in replay | | recordCanvas | boolean | false | Record canvas element changes | | sampling | RumRecorderConfig['sampling'] | - | rrweb sampling config for the session recorder | | 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 | | disableIntercom | boolean | false | Disable the Intercom integration | | disablePreflight | boolean | false | Skip the CORS preflight (OPTIONS) request | | ignoreUrls | IgnoreUrls | - | URL patterns to leave untraced | | instrumentations | Instrumentations | - | Override which instrumentations are enabled | | screenNameOption | ScreenNameOption | - | How the screen name is derived: routeOnly, titleOnly or full | | exporterProtocol | 'proto' | 'json' | 'json' | OTLP protocol format | | sessionStorage | 'cookie' | 'localStorage' | 'cookie' | Session ID storage method | | tracePropagationTargets | (string | RegExp)[] | - | Domains or patterns to send trace headers to |

Peer Dependencies

None.

License

See LICENSE in this package.

Part of sophonz-js.