Use the SDK in a single-page app

In a single-page app, start the SDK once when the app boots. It follows route changes on its own: you do not send page views.

Start the SDK once

Call Flamio.init in the code that runs once per page load — your entry file or root component — not in a route or page component.

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { Flamio } from '@flamioai/web-sdk';
import { App } from './App';

Flamio.init({
  projectKey: 'YOUR_KEY_HERE',
  endpoint: 'https://api.flamio.org/api',
  version: import.meta.env.VITE_APP_VERSION,
});

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

YOUR_KEY_HERE is your project's API key from Flamio On-Live > Setup. VITE_APP_VERSION is an environment variable you set at build time with your release version. For Next.js, see the Next.js example.

A second Flamio.init call is ignored, so a component that mounts twice does no harm. Do not call Flamio.stop() in the cleanup of a component that stays mounted: in React's Strict Mode during development, that ends the session and starts a new one.

Route changes are recorded for you

The SDK sees every route change made through the browser's History API — pushState, replaceState, and the back and forward buttons. Next.js, React Router, Vue Router, Angular Router, SvelteKit and Nuxt all route this way.

On each route change:

• The replay follows the visitor to the new route.
• Your urlAllowlist and urlBlocklist rules are checked again. Recording stops on a route that does not pass and resumes on the next one that does.
• Scroll depth is measured again for the new route.

Web Vitals belong to the page load

LCP, INP and CLS are reported for the page the browser actually loaded, not for each client-side route. A visit that loads the app once and then moves through ten routes has one set of Web Vitals.

Set your release version

Pass version from your build, so you can compare releases in On-Live. Use the same value your deploy uses, such as a semantic version or a commit hash.

Long-lived tabs

• When a tab stays hidden, or stays visible but untouched for idlePauseMs (5 minutes by default), recording pauses. Showing the tab again or the next interaction resumes the same session.
• After 30 minutes without activity, the session ends. If the visitor comes back to the tab later, their next interaction starts a new session.

Related

• Configuration options
• API reference
• Install the web SDK