@faurya/web

Browser-specific analytics for the Faurya SDK.

Overview

@faurya/web provides browser adapters (localStorage, fetch), automatic SPA pageview tracking, singleton client management, browser metadata collection, environment guards, and cross-domain tracking helpers. It builds on @faurya/core.

Install

npm install @faurya/web

Usage

import { initFaurya, getFauryaClient } from '@faurya/web'

const client = await initFaurya({
  websiteId: 'my-site',
  autoCapturePageviews: true,
  allowLocalhost: true,  // optional: enable localhost tracking
})

client.track('click', { target: 'hero-cta' })

// Later, from any module:
const sameClient = getFauryaClient()

client.track('click', { target: 'hero-cta' }) queues a custom request body with browser metadata and:

extraData: {
  eventName: 'click',
  target: 'hero-cta',
}

Features

• Auto-pageview tracking: Patches History API for SPA route changes
• localStorage persistence: Visitor/session IDs survive page reloads
• Singleton pattern: One client per app via initFaurya() / getFauryaClient()
• Graceful fallback: Falls back to memory if localStorage is unavailable
• Environment guards: Silently disables tracking on localhost, file://, iframes, bots
• Cross-domain tracking: getTrackingParams() and buildCrossDomainUrl()
• URL param restore: Reads visitor/session from URL on init, cleans up after
• SSR-safe behavior: Returns a no-op client when browser globals are unavailable

Runtime Rules

• Use @faurya/web for browser analytics.
• In SSR/non-browser runtimes, initFaurya() returns a no-op client and does not start browser-only tracking.
• Browser-only events include pageview, pageview_end, attention, DOM goals, and DOM scroll goals.

Configuration

| Option | Default | Description | |--------|---------|-------------| | allowLocalhost | false | Enable tracking on localhost | | allowIframe | false | Enable tracking in iframes | | allowedHostnames | undefined | Hostnames for cross-domain tracking |

License

MIT