Beacon JavaScript / TypeScript SDK

The Beacon JavaScript / TypeScript SDK provides lightweight, browser-native integration for web applications. Under 5 KB gzipped, it includes automatic page view tracking, session management, and error tracking with full TypeScript definitions.

Installation

Install via npm:

npm install @softagility/beacon-js

The package ships ESM, CommonJS, and UMD builds:

System Requirements

• Any modern browser (Chrome, Firefox, Safari, Edge)
• No dependencies

Configuration

import { Beacon } from '@softagility/beacon-js'

const beacon = Beacon.init({
  apiKey: 'your-api-key',
  sourceApp: 'MyWebApp',
  sourceVersion: '1.2.0',
})

beacon.identify('user-123')

Configuration Options

Identifying Users

Identify the current user to associate events with an actor:

beacon.identify('user-123')

Call identify before or after tracking events. Once set, all subsequent calls use this actor. If not called, the SDK generates an anonymous device ID that persists in localStorage.

Tracking Events

Events are organized by category and name, with optional properties.

Basic Event

beacon.track('ui', 'button_clicked', {
  button_name: 'export',
  screen: 'dashboard',
})

Event Limits

• Category: max 128 characters
• Name: max 256 characters
• Properties: max 20 per event, keys max 64 chars, string values max 256 chars
• Categories starting with _ are reserved and will be ignored

Page View Tracking

Page views are tracked automatically by default when the URL changes (via pushState and popstate). You can also track manually:

beacon.pageView()

// Or with a custom URL and properties
beacon.pageView('/custom-path', { section: 'reports' })

Disable auto-tracking with autoPageViews: false in the config.

Error Tracking

Track JavaScript errors with severity levels. Breadcrumbs from recent track() calls are attached automatically.

try {
  processOrder(order)
} catch (err) {
  beacon.trackError(err, 'non_fatal')
  throw err
}

Severity options: 'fatal' and 'non_fatal' (default).

Session Management

Sessions are managed automatically based on user activity. A new session starts on the first event and rotates after sessionTimeoutMinutes of inactivity. The SDK handles visibilitychange and beforeunload events to end sessions when the user leaves.

Get the current session ID:

const sessionId = beacon.getSessionId()

Flushing Events

Events are batched and sent on a timer (flushIntervalMs) or when the batch size is reached. On page unload, the SDK uses fetch with keepalive: true to deliver remaining events.

To flush manually:

await beacon.flush()

Privacy Controls

The SDK supports opt-out and opt-in for user consent:

// Opt out — stops tracking, clears queue
beacon.optOut()

// Opt back in — resumes tracking
beacon.optIn()

Opt-out state persists in localStorage across sessions.

Reset

Clear all state (session, queue, breadcrumbs, actor ID) and generate a new anonymous ID:

beacon.reset()

Use this on logout to separate user sessions.

Event Definitions

Register known events for import into the Beacon portal's allowlist:

beacon.events.define('reports', 'report_exported')
beacon.events.define('ui', 'button_clicked')

const manifest = beacon.events.exportManifest()

Destroy

Tear down the SDK instance, flush pending events, and remove event listeners:

beacon.destroy()

Environment Collection

The SDK automatically collects browser environment data and sends it as a header with each request:

• Browser name and version
• Screen and viewport dimensions
• Language and platform
• Device type (desktop/mobile/tablet)
• Connection type (when available)

No PII is collected.

Singleton Pattern

Beacon.init() returns a singleton. Calling it again returns the existing instance. If the SDK is loaded in a non-browser environment (SSR), it returns a safe no-op instance.

Next Steps

• Getting Started for a general overview
• API Reference for direct HTTP integration
• Pricing for plan details