Flowsery

Privacy-focused website analytics for modern apps and simple script-tag installs.

Use Flowsery if you want:

• a quick npm setup for React, Next.js, Vue, Svelte, or plain JavaScript
• a hosted browser script you can drop into any site
• optional proxying through your own domain
• automatic pageviews, outbound link tracking, downloads, and heartbeat events

Install

npm install flowsery

Quick Start

Initialize Flowsery with your website ID. That is enough to start automatic pageview tracking.

import { initFlowsery } from 'flowsery';

const flowsery = await initFlowsery({
  websiteId: 'flid_******',
});

Use the returned client anywhere in your app:

flowsery.trackEvent('signup', { plan: 'pro' });

flowsery.identify({
  userId: 'usr_123',
  name: 'John Doe',
});

flowsery.trackPayment({
  amount: 29,
  currency: 'USD',
  transactionId: 'pay_123',
});

Cookieless Mode

If you do not want Flowsery to create visitor and session cookies, enable cookieless mode:

import { initFlowsery } from 'flowsery';

const flowsery = await initFlowsery({
  websiteId: 'flid_******',
  cookieless: true,
});

Proxy Setup

If you proxy tracking through your own domain, point apiBase at your site:

import { initFlowsery } from 'flowsery';

const flowsery = await initFlowsery({
  websiteId: 'flid_******',
  apiBase: 'https://example.com',
});

Typical proxy setup:

• /js/main.js serves the Flowsery browser bundle
• /api/track proxies to https://analytics.flowsery.com/analytics/events

Session Recordings

Flowsery can capture session recordings (rrweb-based DOM replays, plus console errors, failed network requests, and rage clicks). Recording ships as a separate bundle so the core tracker stays small — it is only fetched when you opt in.

Via npm

Set recording: true and Flowsery lazy-loads the recording bundle for you:

import { initFlowsery } from 'flowsery';

const flowsery = await initFlowsery({
  websiteId: 'flid_******',
  recording: true,
});

The recording bundle reuses the same visitor and session IDs as the main tracker, so it respects cookieless mode and never records if the visitor is excluded.

Via script tag

Add the data-recording attribute and Flowsery injects the recording bundle:

<script
  defer
  data-fl-website-id="flid_******"
  data-recording
  src="https://cdn.flowsery.com/main.js"
></script>

Sampling

On high-traffic sites you rarely need to record every visit. Two independent rates control this, both set here on the client (0–100, default 100 — record and analyze everything):

• recordingSampleRate (data-recording-sample) — the share of sessions that get recorded. The browser decides, so unsampled sessions never download the recording bundle. The decision is deterministic per session, so a visitor is recorded (or not) consistently across reloads and page navigations.
• aiSampleRate (data-ai-sample) — the share of recorded sessions sent to AI session analysis. Sent to Flowsery in the recording handshake and applied server-side, since AI analysis runs after the page has closed.

The two multiply: a recording rate of 30 and an AI rate of 50 records ~30% of sessions and AI-analyzes ~15% (30% × 50%) of them — the rest stay fully replayable, just not AI-analyzed.

Via npm:

const flowsery = await initFlowsery({
  websiteId: 'flid_******',
  recording: true,
  recordingSampleRate: 30,
  aiSampleRate: 50,
});

Via script tag:

<script
  defer
  data-fl-website-id="flid_******"
  data-recording
  data-recording-sample="30"
  data-ai-sample="50"
  src="https://cdn.flowsery.com/main.js"
></script>

Script Tag

If you prefer not to use npm, you can install Flowsery with a script tag.

Direct install

<script>
  window.flowsery =
    window.flowsery ||
    function () {
      (window.flowsery.q = window.flowsery.q || []).push(arguments);
    };
</script>
<script
  defer
  data-fl-website-id="flid_******"
  src="https://cdn.flowsery.com/main.js"
></script>

data-fl-website-id is the only required attribute. See script-configuration for the full list of optional attributes — including data-domain, which only matters when you want a single visitor cookie shared across subdomains.

Proxy install

<script>
  window.flowsery =
    window.flowsery ||
    function () {
      (window.flowsery.q = window.flowsery.q || []).push(arguments);
    };
</script>
<script
  defer
  data-fl-website-id="flid_******"
  src="https://example.com/js/main.js"
></script>

What Flowsery Tracks Automatically

• pageviews, including SPA navigation
• heartbeat events with scroll depth, visibility, and interaction count
• outbound link clicks
• file downloads
• visitor and session IDs, unless cookieless mode is enabled
• UTM, ref, source, and via parameters

Common Methods

initFlowsery() returns a client with:

• trackEvent(name, metadata?)
• trackPayment(data)
• trackPageview()
• identify(data)
• stop()
• reset()
• getTrackingParams()
• buildCrossDomainUrl(url)
• getVisitorId()
• getSessionId()

Configuration

type FlowseryConfig = {
  websiteId: string;
  apiBase?: string;
  domain?: string;
  cookieless?: boolean;
  local?: boolean;
  allowFileProtocol?: boolean;
  allowIframe?: boolean;
  disablePayments?: boolean;
  disableConsole?: boolean;
  allowedHostnames?: string[];
  hashMode?: boolean;
  recording?: boolean;
  recordingSampleRate?: number;
  aiSampleRate?: number;
};

Build

bun install
bun run build

Build output:

• dist/main.js
• dist/main.hash.js
• dist/script.js
• dist/script.hash.js
• dist/recording.js
• dist/recording.hash.js
• dist/index.mjs
• dist/index.cjs

Docs

For full setup guides and configuration details, see:

• https://flowsery.com/docs/npm-sdk
• https://flowsery.com/docs/script-configuration