@ffanalytics/sdk

Browser SDK for AnalyticsFF. One call captures pageviews (including SPA navigation), clicks and uncaught errors; add your own events on top.

npm install @ffanalytics/sdk

Usage

import { init, identify, track, register, unregister, reset } from "@ffanalytics/sdk";

init({ key: "pk_..." });

identify(user.id, { plan: "pro" }); // after login
track("report_exported", { format: "csv" });
reset(); // on logout

register(properties) adds properties to every event after it, autocaptured ones included, until unregister(key) removes one. They live in memory only, so a reload or a closed tab clears them:

register({ replay_id: "r_81f2", instrument: "NQZ6" }); // when the replay opens
unregister("replay_id"); // when it closes

The pk_ key is a publishable project key: it can only send events, so it is safe to ship in client code.

Feature flags

import { getFlag, onFlags } from "@ffanalytics/sdk";

onFlags(() => {
  if (getFlag("new-onboarding") === "test") showNewOnboarding();
});

On load the SDK asks which variant of each flag this browser gets, and keeps the answer for the next page load. getFlag(key) returns the variant, or undefined when the flag is off for this browser or nothing has arrived yet; on a first visit that is the first moment after load, which is why onFlags exists. The first answer per flag on a page is recorded as a $feature_flag_called event, and every event carries $feature/<key> for each flag that is on.

Variants are assigned per browser, so logging in doesn't change them. reset() starts a new browser id and asks again.

Options

| Option | Default | | |---|---|---| | key | required | Publishable project key | | host | https://us.i.analyticsff.com | Ingest address, e.g. your own subdomain | | release | "" | Commit SHA of the running build; ties events to code changes | | autocapture | true | false, or { pageviews, clicks, errors } to pick | | flushIntervalMs | 5000 | How often queued events are sent | | maxBatchSize | 20 | Send early once this many events are queued | | replay | off | { sampleRate, canvasFps, maskInputs } records sessions to watch back; see below | | flags | true | false stops the request for feature flag variants on load | | debug | false | Log every event to the console |

Controlling autocapture in markup

<button data-ff-event="signup_cta">Sign up</button>      <!-- named event instead of $click -->
<a data-ff-plan="pro" href="/pricing">Pricing</a>        <!-- adds { plan: "pro" } -->
<div data-ff-ignore>...</div>                             <!-- nothing inside is captured -->

Session recording

init({ key: "pk_...", replay: { sampleRate: 0.25 } }); // 0.25 records a quarter of sessions; 1 records all

The recorder loads only when replay is set, so pages without it stay small. It captures the page and every change to it, not video, and pauses while the tab is hidden or the session has gone idle.

Every form field plays back as asterisks. To see what people type, keep only password fields masked:

init({ key: "pk_...", replay: { sampleRate: 1, maskInputs: "passwords" } }); // "all" (default) or "passwords"

<div class="ff-mask">Account balance: $4,210</div>   <!-- text replaced with asterisks -->
<div class="ff-block">...</div>                       <!-- recorded as an empty box of the same size -->

Canvas content (charts drawn on <canvas>) plays back blank unless you set canvasFps, which records each canvas that many times a second:

init({ key: "pk_...", replay: { sampleRate: 1, canvasFps: 1 } });

It is off by default because ff-mask can't reach inside a canvas: anything drawn there is recorded as it looks. ff-block on a canvas still leaves it out.

Privacy

• Input values are never read; only the visible text of buttons and links. Session recordings mask every input.
• Ids live in localStorage (no cookies). reset() clears them.
• Safe to import in server-rendered code; call init from client code only.

License

MIT