BeaconDeveloper GuideSDKsJavaScript / TypeScript

Beacon JavaScript / TypeScript SDK

The Beacon JavaScript / TypeScript SDK provides lightweight, browser-native integration for web applications. Under 6 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:

FormatEntry
ESMdist/beacon.esm.js
CommonJSdist/beacon.cjs.js
UMD (browser)dist/beacon.umd.js
Typesdist/beacon.d.ts

System Requirements

  • Any modern browser (Chrome, Firefox, Safari, Edge)
  • Node.js 18 or later (for SSR / Node imports — the SDK falls back to a no-op instance in non-browser environments, but the import itself requires modern Node)
  • No runtime 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

OptionTypeDefaultDescription
apiKeystring—Your Beacon API key (required)
sourceAppstring—Your product’s slug as registered in the Beacon dashboard (e.g., "inventory-manager"). Must match a registered product or events are rejected with UNRECOGNIZED_PRODUCT. Max 256 chars on the wire. (required)
sourceVersionstring—Your application’s version string. Max 128 chars on the wire. (required)
endpointstringhttps://api.beacon.softagility.comAPI base URL override
sessionTimeoutMinutesnumber30Inactivity timeout before session rotates (1-1440)
autoPageViewsbooleantrueAuto-track page views on route changes
flushIntervalMsnumber10000Flush interval in milliseconds (1000-300000)
maxBatchSizenumber50Events per flush batch (1-1000)
maxQueueSizenumber5000Maximum in-memory queue depth (100-10000)
maxBreadcrumbsnumber25Breadcrumb ring buffer size (0-200, 0 disables)
debugbooleanfalseLog SDK actions to console

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. The SDK hooks pushState, replaceState, and popstate to detect URL changes, and emits an initial page view on init() when autoPageViews is enabled. 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. Inactivity is measured as time since the last SDK call that touches event state — track(), pageView(), identify(), etc. After sessionTimeoutMinutes of inactivity, the next event rotates into a fresh session.

The SDK also wires up two browser lifecycle events:

  • visibilitychange (when the tab becomes hidden) triggers an immediate flush of queued events but does not end the session — the user may return.
  • beforeunload (when the page unloads) ends the active session and flushes remaining events.

Get the current session ID or actor ID:

const sessionId = beacon.getSessionId()
const actorId = beacon.getActorId()

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: clears timers, removes event listeners, clears identity / queue / breadcrumbs / event definitions in-memory state.

beacon.destroy()

destroy() does not flush pending events. To deliver them before tearing down, call await beacon.flush() first.

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