Widget SDK
Capture user sessions automatically with a lightweight JavaScript SDK.
Installation
npm
bash
npm install @usercontext/widgetScript Tag
html
<script src="https://cdn.usercontext.com/widget.js"></script>
<script>
UserContext.init({
apiKey: 'uc_your_api_key',
});
</script>Configuration
Pass a configuration object to UserContext.init().
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | required | Your project API key (uc_...) |
endpoint | string | https://api.usercontext.com | API endpoint URL |
debug | boolean | false | Enable debug logging to console |
captureConsoleLog | boolean | false | Also capture console.log and console.info |
flushIntervalMs | number | 5000 | How often to flush the log buffer (ms) |
maxBufferSize | number | 50 | Flush when buffer reaches this many entries |
Methods
UserContext.init(config)
Initialize the SDK. Call once on page load.
typescript
await UserContext.init({
apiKey: 'uc_...',
debug: true,
captureConsoleLog: true,
});UserContext.identify(userId, traits?)
Associate the session with a user.
typescript
UserContext.identify('user_123', {
plan: 'pro',
company: 'Acme Corp',
});UserContext.reportIssue(description)
Create an issue from the current session. Returns the issue ID.
typescript
const issueId = await UserContext.reportIssue('Checkout button does nothing');UserContext.captureError(error)
Manually capture an error.
typescript
try {
riskyOperation();
} catch (e) {
UserContext.captureError(e);
}What’s captured automatically
| Category | What | Event Type |
|---|---|---|
| Errors | Uncaught exceptions, unhandled promise rejections | log |
| Console | console.error, console.warn (optionally log/info) | log |
| Network | Failed fetch/XHR requests (status 400+) | log |
| Clicks | All click events with element selector, text, coordinates | click |
| Navigation | URL changes via pushState, replaceState, popstate, hashchange | navigation |