API reference

Every method is static: you call it on the Flamio object you import. No method throws. If something fails, the SDK stays quiet and your page keeps working.

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

Flamio.init()

Flamio.init(config: FlamioConfig): Flamio | null

Starts the SDK. Call it once per page load, as early as possible.

Parameters

Returns

The SDK instance when it started. With consent: 'wait' or 'denied' you also get the instance, but nothing is recorded until you call Flamio.consent('granted').

null when this page load will not be recorded:

• The code runs outside a browser, for example during server-side rendering.
• The visit is outside your sampleRate.
• Flamio recently refused this project key in this browser. See Troubleshooting.
• The browser cannot run the SDK: the page is not served over HTTPS, or the browser is older than the supported versions.

The instance has no public methods. Use the return value only to tell whether the SDK started.

A second init call returns the running instance and ignores the new options. To apply new options, call Flamio.stop() first.

Example

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

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

if (flamio === null) {
  console.info('This page load is not recorded by Flamio.');
}

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

Flamio.identify()

Flamio.identify(userId: string, traits?: Record<string, unknown>): void

Attaches a signed-in user to the current session. Call it after Flamio.init, as soon as you know who the user is.

Parameters

Returns

Nothing.

Behavior

• Calls made before Flamio.init, or after Flamio.init returned null, are ignored.
• The whole current session is attributed to the user, including what was recorded before the call.
• Before consent is granted, the identity waits in memory and is sent once you call Flamio.consent('granted').
• Calling it again with another ID or other traits replaces them.

Example

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

Flamio.identify('user_123', {
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  plan: 'pro',
});

More in Identify signed-in users.

Flamio.consent()

Flamio.consent(status: 'granted' | 'denied'): void

Tells the SDK the visitor's consent decision. Use it with consent: 'wait' in Flamio.init.

Parameters

Returns

Nothing.

Behavior

• After 'granted', the SDK may store its anonymous visitor ID in the browser and send data to Flamio.
• After 'denied', data already sent stays in Flamio. A later 'granted' on the same page starts recording again.
• The SDK does not remember the decision between page loads. Pass it on every page.
• Calls made before Flamio.init, or after Flamio.init returned null, do nothing.

Example

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

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

// Later, from your cookie banner:
Flamio.consent('granted');

More in Record only after consent.

Flamio.stop()

Flamio.stop(): void

Stops recording on this page, sends what is still waiting to be uploaded, and removes the SDK from the page. After stop, identify and consent do nothing until you call Flamio.init again, which starts a new session.

Returns

Nothing.

Example

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

function onSignOut(): void {
  Flamio.stop();
}

What the SDK changes on the page

To observe route changes, failed requests and console errors, the SDK wraps these browser functions while it records:

• history.pushState and history.replaceState
• fetch and XMLHttpRequest
• console.error, and console.warn when captureConsoleWarn is on

The wrappers call the original functions with the same arguments and return their results. Flamio.stop() and Flamio.consent('denied') put the originals back.

Methods not to use

The 0.9.0 package also contains Flamio.guide() and Flamio.stopGuide(). They belong to an in-page guide that is not available to customers. Do not call them.

Types

The package exports the FlamioConfig type for the options of init. Other types it exports describe Flamio's internal data and can change in any release. Do not depend on them.

Related

• Configuration options
• Single-page apps
• Changelog