Install the web SDK

The web SDK @flamioai/web-sdk records how real visitors use your site and sends their sessions to Flamio On-Live. This reference covers version 0.9.0, the version published as latest on npm.

Before you begin

• A Flamio project for your site, selected in the sidebar project switcher.
• Flamio On-Live enabled for that project, with an API key. Both happen on Flamio On-Live > Setup and need the Editor, Admin or Owner role.
• Your site is served over HTTPS. http://localhost also works for local testing.
• You can change and deploy your site's code. Flamio cannot add the SDK for you.

Install

npm install @flamioai/web-sdk

import { Flamio } from '@flamioai/web-sdk';

Flamio.init({
  projectKey: 'YOUR_KEY_HERE',
  endpoint: 'https://api.flamio.org/api'
});

Framework examples

'use client';

import { useEffect } from 'react';
import { Flamio } from '@flamioai/web-sdk';

export function FlamioRecorder() {
  useEffect(() => {
    Flamio.init({
      projectKey: 'YOUR_KEY_HERE',
      endpoint: 'https://api.flamio.org/api',
    });
  }, []);

  return null;
}

YOUR_KEY_HERE is your project's API key from Flamio On-Live > Setup.

In a Next.js App Router project, render the component once in your root layout:

import type { ReactNode } from 'react';
import { FlamioRecorder } from './flamio-recorder';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <FlamioRecorder />
        {children}
      </body>
    </html>
  );
}

The plain HTML example loads the SDK from esm.sh with the version pinned. Put the script on every page you want recorded.

Your API key ends up in your site's public JavaScript. That is expected: Allowed domains in your project settings decides which websites may send sessions with it. See Project settings.

Verify it works

1. Open your deployed site in a new browser window and use it for a minute: click, scroll, open a few pages.
2. In Flamio, open or reload Flamio On-Live > Setup. Step 4 changes from Waiting for first data… to Data is flowing. Click Go to Overview.
3. Open Visits. A visit that is still in progress carries a green Live pill.

To check from the browser, add debug: true to Flamio.init and open the browser console. [Flamio] Initialized means the SDK started. In the Network panel, requests to api.flamio.org should succeed. Remove debug before you ship.

Nothing arrives? See Troubleshooting.

Browser support and size

• Browsers: current Chrome, Edge, Firefox and Safari, on desktop and mobile. The minimum versions are Chrome and Edge 92, Firefox 95 and Safari 15.4. In older browsers the SDK does not start and does not throw errors.
• HTTPS: the SDK runs only on pages served over HTTPS, or on localhost.
• Size: the SDK loads about 17 KB (gzip) on every page. The recorder, about 23 KB more, downloads only on pages that are actually recorded. Visitors outside your sample, without consent or on a blocked page never download it.
• Safety: no SDK method throws into your code. If something fails, recording stops and your page keeps working.

Next steps