@trlogic/tracker-web

Formica Tracker Web SDK — browser-side fraud detection, risk scoring, and event tracking. Architecture mirrors the Android and iOS Tracker SDKs (DI container, collector pipeline, event coordinator, filter engine).

Installation

npm install @trlogic/tracker-web

Quick Start

import { TrackerSDK, TrackerConfiguration } from "@trlogic/tracker-web";

const config: TrackerConfiguration = {
  tenant: "your-tenant",
  apiUrl: "https://your-api-url.com",
  apiKey: "your-api-key",
};

const tracker = new TrackerSDK.Builder().setConfiguration(config).build();

tracker.initialize({
  onSuccess: () => console.log("Tracker initialized"),
  onError: (error) => console.error("Init failed", error),
});

Features

Event Tracking

The SDK automatically tracks browser events via built-in listeners:

| Event Type | Trigger | | ------------------- | ------------------------------------------------ | | PAGE_VIEW | SPA navigation (pushState/replaceState/popstate) | | CLICK | Document click events | | SCROLL | Window scroll events (debounced) | | VISIBILITY_CHANGE | Tab focus/blur | | RISK_ALERT | Risk score threshold exceeded |

Custom Events

// Fire-and-forget
tracker.triggerCustomEvent("checkout", { orderId: "12345", amount: 99.99 });

// With callback
tracker.triggerCustomEventSync(
  "payment",
  { method: "card" },
  {
    onSuccess: (result) => console.log("Event sent", result),
    onError: (error) => console.error("Failed", error),
  },
);

User-Defined Values

tracker.setUserDefinedValue("userId", "usr_abc123");
tracker.setUserDefinedValue("sessionType", "premium");

const values = tracker.getUserDefinedValues();

Variable Collection (39+ Types)

| Category | Variables | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Device | DEVICE_FINGERPRINT, SCREEN_RESOLUTION, USER_AGENT, BROWSER, OS, LANGUAGE, TIMEZONE, PLATFORM, SDK_VERSION | | Network | IP_ADDRESS, REACHABLE | | Risk Metrics | SUSPICIOUS_ACTIVITY, SUSPICIOUS_BROWSER, REMOTE_ACCESS_SCORE, REMOTE_ACCESS_FLAGS_JSON, ENVIRONMENT_CHANGE_SCORE, ENVIRONMENT_CHANGE_FLAGS | | Behavior | NO_MOUSE_MOVE_DURATION_MS, CLICK_ONLY_PATTERN, FAST_PAGE_TRANSITION, NAVIGATION_VELOCITY, FORM_FILL_ANOMALY, INPUT_PASTE_RATIO | | Detection | HEADLESS_INDICATOR_COUNT, REDIRECT_DETECTED | | Screen | VIEW_DURATION, URL, ELEMENT, COOKIE, JAVASCRIPT, EVENT |

Risk Scoring

The SecurityCollector computes a composite remote access score (0–1) from:

• Unnatural mouse movement patterns
• Clipboard paste anomalies
• Low FPS detection (screen sharing/remote control)
• Click-only patterns (no mouse movement)
• Headless browser indicators (WebGL, plugins, webdriver)
• Environment change detection (language/timezone/OS/browser drift)
• Form fill timing anomalies

Configuration

const config: TrackerConfiguration = {
  tenant: "your-tenant",
  apiUrl: "https://api.example.com",
  apiKey: "your-api-key",
  timeout: 10000, // HTTP timeout (ms), default: 10000
  queueProcessInterval: 5000, // Event queue drain interval (ms), default: 5000
};

Bundle Formats

| Format | File | Use Case | | ------ | ----------------------- | -------------------------------------------- | | ESM | dist/index.esm.min.js | Modern bundlers (Vite, Webpack 5, Rollup) | | UMD | dist/index.umd.min.js | Universal (Node.js + browser) | | AMD | dist/index.amd.js | RequireJS | | IIFE | dist/index.js | <script> tag (exposes TrackerWeb global) | | CJS | dist/bundle.js | Legacy Node.js / CommonJS |

Script Tag Usage

<script src="dist/index.js"></script>
<script>
  const { TrackerSDK } = TrackerWeb;
  const tracker = new TrackerSDK.Builder()
    .setConfiguration({ tenant: "t", apiUrl: "https://...", apiKey: "k" })
    .build();
  tracker.initialize();
</script>

Architecture

src/
├── core/
│   ├── model/          # TrackerEventType, TrackerVariableType, FilterOperator, etc.
│   ├── contract/       # DataCollector, EventStorage, NetworkService interfaces
│   ├── engine/         # FilterEngine, EventCoordinator, TrackerEngine
│   ├── base/           # BaseDataCollector, CachedDataCollector
│   └── scheduler/      # PeriodicDataScheduler
├── collector/          # DeviceCollector, NetworkCollector, SecurityCollector, ScreenActivityCollector
├── listener/           # PageViewListener, ClickListener, ScrollListener, VisibilityListener
├── service/            # InMemoryEventStorage, DefaultNetworkService, EventService
├── di/                 # DataPayload, TrackerModule (DI container)
├── util/               # Logger, HttpClient, BrowserDetector, FilterUtil
├── tracker.ts          # TrackerSDK (public API with Builder pattern)
└── index.ts            # Barrel exports

Development

# Install dependencies
npm install

# Build all formats
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

# Format code
npm run format

# Check formatting
npm run format:check

# Clean build artifacts
npm run clean

Testing with Tracker CLI

Start the local test server:

# In the tracker CLI project
./tracker server -p 8000

# Web SDK config is served at:
# GET http://localhost:8000/sentinel/v1
# Headers: api-key, tenant, platform: web

Then use the example app:

cd example
npm install
npm start
# Open http://localhost:3000

Browser Support

• Chrome 80+
• Firefox 78+
• Safari 14+
• Edge 80+

License

This project is licensed under the terms specified in the LICENSE file.