Getting started

Installation

Install the core SDK plus any framework wrapper that matches your stack.

Script tag

The fastest way to install: paste one tag before the closing </body>, no build step required.

html

<script src="https://flusterduck.com/d.js" data-key="fd_pub_xxxxxxxxxxxx" data-dnt="false" async></script>

Replace fd_pub_xxxxxxxxxxxx with your site's publishable key. Onboarding shows it once, when you add the site. Lost it? Settings > Sites > New key mints a fresh one (the old one stops working). Keep data-dnt="false": the SDK does not capture form values or user-typed text, and short element labels are PII-redacted before they leave the browser. Without it, the SDK skips every visitor whose browser or privacy extension sends Do Not Track or Global Privacy Control, and those boundaries stay the same either way.

The bootstrap reads its config from document.currentScript, and falls back to document.querySelector('script[data-key^="fd_pub_"]') if that's unset, so injecting the tag dynamically (document.createElement('script'), tag managers, etc.) works too, as long as async and data-key are set.

Loading & performance

The tag is async, not defer: a slow or unreachable CDN can never block the host page's parse, paint, or DOMContentLoaded. Once it loads, the SDK is fire-and-forget. Events are sent with navigator.sendBeacon or a fetch with keepalive: true, and init() runs inside a try/catch so an SDK failure can never throw into your page.

Want zero third-party runtime dependency, or run under a strict CSP that forbids third-party script hosts? Install via npm instead (below) and self-host the bundle.

Verifying locally

Flusterduck treats non-user traffic as noise: events sent from localhost (or other dev hosts) and events from automated browsers are acknowledged but never stored, so a developer smoke-test (thanks Claude) can't burn your session quota, skew scores, or create phantom issues. To see events actually land while developing, add data-env="development" to the tag (or pass environment: 'development' to init), which stands those filters down. Accepted names: development, dev, test, testing, staging, local. Those visits are stored and tagged as development, so you can watch them arrive, but they never count toward your plan's sessions, scores, or issues. Remove the attribute before shipping, or your real visitors are tagged as development too. The test-suite CLI walks the whole verification for you.

Packages

Install the core SDK plus any framework wrapper that matches your stack.

Core SDK

bash

pnpm add flusterduck

Required for every project. The framework wrappers depend on it.

Framework wrappers

Pick the one that matches your stack. Each command installs the core SDK alongside the wrapper.

Next.js

Works with both the App Router and the Pages Router.

bash

pnpm add flusterduck @flusterduck/next

React

For Vite, CRA, or any other React app.

bash

pnpm add flusterduck @flusterduck/react

Vue 3

bash

pnpm add flusterduck @flusterduck/vue

SvelteKit

bash

pnpm add flusterduck @flusterduck/svelte

Nuxt 3

bash

pnpm add flusterduck @flusterduck/nuxt

Not using a framework wrapper? Initialize the SDK directly with init(). It works in any browser environment.

Publishable key

Your publishable key starts with fd_pub_. It's shown once, when you add the site. Settings > Sites shows its prefix, and New key there mints a replacement if you lost the full key.

Set it as an environment variable:

bash

# Next.js
NEXT_PUBLIC_FLUSTERDUCK_KEY=fd_pub_xxxxxxxxxxxx

# Vite / Vue / SvelteKit
VITE_FLUSTERDUCK_KEY=fd_pub_xxxxxxxxxxxx

# Nuxt
NUXT_PUBLIC_FLUSTERDUCK_KEY=fd_pub_xxxxxxxxxxxx

The fd_pub_ key is safe in client-side code. It can only send signals. It can't read data or modify your account.

What each package does

Package	What it does
`flusterduck`	Core browser SDK. On-device signal detection/classification and event buffering.
`@flusterduck/next`	`FlusterduckScript` component + `useFlusterduck` hook for Next.js App Router and Pages Router.
`@flusterduck/react`	`FlusterduckProvider` component + `useFlusterduck` hook.
`@flusterduck/vue`	Vue 3 plugin + `useFlusterduck` composable.
`@flusterduck/svelte`	SSR-safe `initFlusterduck()` / `destroyFlusterduck()` plus tracking functions, for calling from `onMount` in SvelteKit. No Svelte store.
`@flusterduck/nuxt`	`createFlusterduckPlugin()` factory you export from a `plugins/*.client.ts` file, plus tracking composables. Doesn't initialize on its own; you wire the plugin file once.

Using the CLI instead

The CLI handles installation and code injection in one command:

bash

npx flusterduck-cli init

See CLI reference for options.

Requirements

Browser environment (the SDK doesn't run server-side)
HTTPS in production
A site and publishable key from the dashboard