@agentuity/analytics

@agentuity/analytics

Browser analytics for Agentuity applications. Track page views, Web Vitals, custom events, and more.

Installation

npm install @agentuity/analytics

Usage

Auto-init (Drop-in)

Set configuration via server-side injection, then import the beacon:

<script>
  window.__AGENTUITY_ANALYTICS__ = {
    enabled: true,
    orgId: 'your-org-id',
    projectId: 'your-project-id',
  };
</script>
<script type="module" src="/path/to/analytics/beacon.js"></script>

Or in a bundler:

import '@agentuity/analytics/beacon';

Programmatic

import { init, track, identify, flush } from '@agentuity/analytics';

// Initialize
init({
  orgId: 'your-org-id',
  projectId: 'your-project-id',
});

// Track events
track('button_click', { button: 'signup' });

// Identify user
identify('user-123', { email: '[e-mail]' });

// Flush pending events
flush();

Features

• Page Views - Automatic tracking with URL, referrer, title
• Web Vitals - FCP, LCP, CLS, INP metrics
• Scroll Depth - Tracks 25%, 50%, 75%, 100% milestones
• SPA Navigation - Tracks route changes in single-page apps
• Click Tracking - Via [data-analytics] attributes
• Error Tracking - JS errors and unhandled rejections
• Custom Events - Track any user action

Configuration

Option	Type	Default	Description
enabled	boolean	true	Enable/disable tracking
orgId	string	-	Organization ID
projectId	string	-	Project ID
isDevmode	boolean	false	Development mode (logs to console)
trackClicks	boolean	true	Track [data-analytics] clicks
trackScroll	boolean	true	Track scroll depth
trackWebVitals	boolean	true	Track Core Web Vitals
trackErrors	boolean	true	Track JS errors
trackSPANavigation	boolean	true	Track SPA route changes
sampleRate	number	1	Sampling rate (0-1)
endpoint	string	/_agentuity/webanalytics/collect	Collect endpoint

Data Collected

The beacon collects:

• Page: URL, path, referrer, title
• Device: Screen size, viewport, device pixel ratio, user agent
• Performance: TTFB, DOM ready, load time, Web Vitals
• Engagement: Scroll depth, time on page
• Context: Language, timezone, UTM parameters
• Geo: Country, region, city (from IP, cached)

Privacy

• Query strings are stripped from URLs to prevent sensitive data leakage
• No cookies used (uses localStorage for visitor ID)
• Geo data cached in sessionStorage
• User opt-out supported via setOptOut(true)

Server Integration

The beacon sends data to /_agentuity/webanalytics/collect by default. Configure your server to:

• Inject window.__AGENTUITY_ANALYTICS__ config
• Handle POST requests to the collect endpoint

Framework Support

Works with any frontend framework:

• React
• Vue
• Svelte
• Solid
• Vanilla JS

No framework-specific code required.