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

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_******"
  data-domain="example.com"
  src="https://cdn.flowsery.com/main.js"
></script>

Proxy install

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

To improve geo accuracy in a proxied setup:

<script
  defer
  data-fl-website-id="flid_******"
  data-domain="example.com"
  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;
};

Build

bun install
bun run build

Build output:

• dist/main.js
• dist/main.hash.js
• dist/script.js
• dist/script.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