The UserALE.js API

Apache Flagon UserALE.js provides a comprehensive JavaScript and TypeScript API for runtime configuration, custom log enrichment/filtering, header injection, and pluggable wire exporters.

Core Lifecycle & Configuration API

options(newConfig?: Partial<Settings.Config>): Settings.Config

Reads or shallow-merges runtime configuration options. Calling options() with no arguments returns the current configuration object.

import * as userale from 'flagon-userale';

userale.options({
  url: 'https://collector.example.com/v1/logs',
  userId: 'user-42',
  toolName: 'checkout-ui',
  toolVersion: '2.5.0',
  exporterFormat: 'otlp-json',
});

start(): void & stop(): void

Starts or halts event capturing and log transmission. Particularly useful when autostart: false (data-autostart="false") is configured until user consent or authentication completes.

userale.options({ autostart: false });
// Later, after user consent:
userale.start();

version: string

Exports the current flagon-userale package version string.

Custom Logging & Filtering Callbacks

addCallbacks(callbacks: Record<string, CallableFunction>): boolean

Registers one or more named callback functions executed sequentially on every packaged log ((log, event) => log | false). Returning false (or any falsy value) drops the log from the queue; returning a modified log object replaces it.

userale.addCallbacks({
  dropIntervalLogs(log) {
    if (log.logType === 'interval') {
      return false;
    }
    return log;
  },
  attachExperimentTag(log, event) {
    return {
      ...log,
      experimentVariant: 'checkout-v2',
    };
  },
});

removeCallbacks(targetKeys: string[]): void

Removes registered callbacks by name:

userale.removeCallbacks(['dropIntervalLogs']);

log(customLog: Logging.CustomLog): boolean

Appends a custom log object directly onto the UserALE queue:

userale.log({
  target: 'checkout-funnel',
  type: 'step_complete',
  logType: 'custom',
  userAction: false,
  details: { step: 2, cartTotal: 149.0 },
});

packageLog(e: Event, detailFcn?: Logging.DynamicDetailFunction): boolean & packageCustomLog(customLogs: Logging.CustomLog, detailFcn: Logging.DynamicDetailFunction, userAction: boolean): boolean

Packages a standard DOM Event or custom metadata object with full UserALE page/session/browser context and enqueues it.

details(config: Configuration, type: Events.AllowedEvents): ((e: Event) => Record<string, unknown>) | null

Returns the default detail-extractor function for a given DOM event type (click, keydown, input, change, wheel, etc.). Note that <input type="password"> values are automatically masked ("********").

getSelector(ele: EventTarget): string & buildPath(e: Event): string[]

Utility helpers that compute a CSS-like element selector (tag#id.class) and full DOM ancestry path array from a DOM Event.

getTargetRect(el: EventTarget | null): TargetRect | null & detectBrowser(): { browser: string; version: string }

• getTargetRect extracts a rounded bounding box ({ x, y, width, height, top, right, bottom, left }) for a DOM element (attached automatically as targetRect on click, dblclick, change, and submit events).
• detectBrowser detects the browser name and version using navigator.userAgentData (User-Agent Client Hints) with a regex fallback and zero external dependencies.

Authentication & Custom HTTP Headers

All HTTP-based exporters (HttpJsonExporter, ProtoJsonExporter, OtlpJsonExporter) construct headers through buildHeaders(config), applying them to both interval fetch() requests and pagehide (fetch(..., { keepalive: true })) flushes.

registerAuthCallback(callback: () => string): boolean & resetAuthCallback(): void

Registers (or resets) a dynamic provider returning the Authorization header value on each batch export:

userale.registerAuthCallback(() => `Bearer ${getCurrentJwtToken()}`);

registerHeadersCallback(callback: () => Record<string, string>): boolean & resetHeadersCallback(): void

Registers (or resets) a dynamic provider returning arbitrary HTTP headers on each batch export:

userale.registerHeadersCallback(() => ({
  'x-tenant-id': 'acme-corp',
  'x-request-source': 'userale-web',
}));

Static headers can also be configured via userale.options({ authHeader: 'Bearer ...', apiKey: '...', headers: { ... } }).

Pluggable Wire Exporters (LogExporter)

UserALE decouples in-memory event packaging from wire serialization and transport via the LogExporter interface:

export interface LogExporter {
  export(logs: Array<Logging.Log>, options?: ExportOptions): Promise<ExportResult>;
  flush?(): Promise<void>;
  shutdown?(): Promise<void>;
}

Built-In Exporters & Helpers

Example: Correlating UserALE Events with W3C Distributed Traces

import * as userale from 'flagon-userale';

userale.options({
  exporterType: 'otlp',
  otlpEndpoint: 'http://localhost:4318/v1/logs',
  toolName: 'storefront-web',
  traceContext: () => ({
    traceId: currentActiveSpan.traceId, // 32-hex W3C trace-id
    spanId: currentActiveSpan.spanId,   // 16-hex W3C span-id
  }),
});

Two-Layer Session Replay & Behavioral DOM Telemetry (#104)

UserALE provides a two-layer session replay architecture that keeps the core bundle dependency-free while supporting both structural DOM telemetry and rrweb-compatible visual playback:

import * as userale from 'flagon-userale';
import * as rrweb from 'rrweb';

userale.startSessionReplay({
  recorder: rrweb.record,
  maxDurationMs: 30_000,
  observeMutations: true,
  detectRageClicks: true,
  flushOnError: true,
});

Contributing

Contributions are welcome! See our Contributing Guide or open an issue on GitHub.