@racoelho/analisa

The browser SDK for Analisa, privacy-first web analytics with no cookies. It tracks page views, custom events, goals, Web Vitals and JavaScript errors, and works with plain HTML, React, Next.js, Vue, Angular or any other framework.

• About 6 KB gzipped, with no runtime dependencies.
• Ships as ESM, CommonJS and a script-tag build (window.Analytics).
• Respects Do Not Track and has a consent switch.

Full documentation: useanalisa.com/docs.

This package was published as @racoelho/analytics up to version 0.2.0. The API is the same: change the package name in your imports and in the script URL.

Install

npm install @racoelho/analisa

Or add the script tag before </body>. The URL pins the 0.2 line, so you get fixes without breaking changes:

<script src="https://cdn.jsdelivr.net/npm/@racoelho/[email protected]/dist/index.global.js"></script>
<script>window.analytics = new Analytics.Analytics({ siteKey: 'YOUR_SITE_KEY' })</script>

Your site key is in the Analisa dashboard, under Apps → your app → Install.

Quick start

import { Analytics } from '@racoelho/analisa'

const analytics = new Analytics({ siteKey: 'YOUR_SITE_KEY' })

// The first page view is sent automatically. Custom events:
analytics.track('button_click', { id: 'cta' })

Events are batched and sent in the background.

In a single-page app, send a page view on each route change:

router.afterEach((to) => analytics.pageview({ path: to.fullPath })) // Vue Router

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | siteKey | string | | Required. Your app's site key. | | endpoint | string | Analisa cloud | Ingestion URL. Only set it if you self-host. | | batchSize | number | 10 | Events per request. | | flushIntervalMs | number | 3000 | How often the queue is sent, in milliseconds. | | respectDNT | boolean | true | Send nothing when the browser has Do Not Track on. | | autoPageview | boolean | true | Send a page view when the SDK starts. | | autoWebVitals | boolean | true | Collect LCP, FCP, CLS, INP and TTFB. | | autoErrors | boolean | true | Capture uncaught errors and unhandled promise rejections. | | debug | boolean | false | Log what the SDK sends to the console. | | context | object | { platform: 'web' } | Overrides the event context. Use it inside an Electron, Tauri or Capacitor webview to report the real platform. |

Methods

| Method | Description | |--------|-------------| | track(name, props?) | Sends a custom event. | | pageview(props?) | Sends a page view, e.g. on a client-side route change. | | identify({ user_id, traits?, id_prop? }) | Links the visitor to one of your users. Persists across reloads and tabs. | | reset() | Call on logout: clears the stored identity and starts a new session. | | captureException(error, props?) | Reports a caught error. | | setConsent('granted' \| 'denied') | Records the visitor's consent. denied also clears the stored identity. | | flush() | Sends the queue now. |

Ready-made events

All arguments are optional, and each method takes a final props object for anything extra.

• Interaction: click(elementId?, elementText?), scroll(depth?)
• Forms: formStart(formId?, formName?), formSubmit(formId?, formName?)
• Content: download(fileName?, fileType?), share(method?, contentType?, itemId?), search(query?, category?)
• Accounts: signup(method?), login(method?), logout()
• E-commerce: viewItem(productId?, productName?, category?, price?), addToCart(productId?, productName?, price?, quantity?), removeFromCart(productId?, productName?), beginCheckout(value?, currency?), purchase(orderId?, value?, currency?, items?)
• Video: videoPlay(videoId?, videoTitle?, duration?), videoPause(videoId?, currentTime?), videoComplete(videoId?, duration?)

analytics.purchase('order-456', 49.9, 'USD', [
  { product_id: 'prod-123', product_name: 'Pro plan', price: 49.9, quantity: 1 },
])
analytics.signup('email', { plan: 'pro' })
analytics.search('pricing', 'docs')

Identifying users

// After login
analytics.identify({
  user_id: 'u_123',
  traits: { plan: 'pro' },
  id_prop: 'plan', // optional: which trait to show as the user's label in the dashboard
})

// On logout
analytics.reset()

Anonymous sessions from before the login are linked to the user. Send your internal user id, not an email or other personal data, unless your privacy policy covers it.

Errors

With autoErrors on (the default), uncaught errors and unhandled rejections are sent as error events, grouped by a stable fingerprint. The same error is sent at most once every 5 seconds, with a cap of 50 errors per page load. To report a caught error:

try {
  doRiskyThing()
} catch (err) {
  analytics.captureException(err, { feature: 'checkout' })
}

Privacy

• No cookies. The SDK stores an anonymous id in localStorage, a session id in sessionStorage and, after identify(), the user id in localStorage (removed by reset()).
• Respects navigator.doNotTrack unless you turn respectDNT off.
• IP addresses are truncated at ingestion and never stored in full.

More in useanalisa.com/docs/gdpr.

Mobile and desktop apps

• React Native and Expo: @racoelho/analisa-react-native
• Electron and Tauri: @racoelho/analisa-desktop
• Anything else: the HTTP ingestion protocol

License

MIT © Rafael Coelho