Flash Analytics Core SDK

This package is the shared JavaScript SDK used by the web, Next.js, and React Native wrappers.

Session access

After any successful track(...) call, you can read the active session and its estimated expiry:

import { FlashAnalytics } from '@flash-analytics/sdk';

const analytics = new FlashAnalytics({
  appId: 'your-app-id',
});

await analytics.track('page_view');

const session = analytics.getSession();

console.log(session?.id);
console.log(session?.estimatedExpiresAt);
console.log(session?.estimatedTtlMs);

getSessionId() still works if you only need the id.

Identify payloads

If an active session already exists, the SDK automatically attaches it when you call identify(...).

await analytics.identify({
  profileId: 'user-123',
  email: '[email protected]',
});

Experiment Auto-Assignment

Enable captureVariants to automatically keep a local cache of experiment assignments in sync throughout the session lifecycle.

import { FlashAnalytics } from '@flash-analytics/sdk';

const analytics = new FlashAnalytics({
  appId: 'your-app-id',
  captureVariants: true,
  // or with options:
  // captureVariants: {
  //   includeInternalProperties: true,
  //   onAssignmentsChanged: (assignments) => console.log('variants updated', assignments),
  // },
});

How the local cache is maintained

Session start (new session ID received from /track): Fetches ALL experiments — profile, session, and event-triggered — and replaces the entire local store. Only fires when the session ID actually changes; repeated track() calls on the same session do not re-fetch.

After identify(): Fetches only profile-mode experiments (user identity just changed) and replaces only the profile-mode entries in the store. Session and event assignments are left untouched.

Session expiry: Removes only session-mode assignments from the store when the cached session TTL runs out. Profile and event assignments survive.

Reading assignments

// All cached assignments — no API call
const all = analytics.getAllExperiments();

// Single experiment — checks cache first, falls back to API if not found
const assignment = await analytics.getExperimentById('checkout-cta');
console.log(assignment?.variantName);

Local store state at each lifecycle point

| Moment | Profile assignments | Session assignments | Event assignments | |---|---|---|---| | After first track() (new session) | fetched | fetched | fetched | | After identify() | re-fetched | unchanged | unchanged | | After session expiry | unchanged | removed | unchanged | | After next track() (new session) | re-fetched | re-fetched | re-fetched |

Remote config

Fetch all resolved parameters once, then read typed values from the returned snapshot.

import { FlashAnalytics } from '@flash-analytics/sdk';

const analytics = new FlashAnalytics({
  appId: 'your-app-id',
  secretKey: 'your-secret',
  endpoint: 'https://api.flashanalytics.app',
  platform: 'web',
  appVersion: '1.2.3',
  buildNumber: '120',
});

analytics.setGlobalProperties({
  plan: 'pro',
  isBetaUser: true,
});

const config = await analytics.fetchRemoteConfig({
  country: 'IN',
});

const featureFlag = config.getBoolean('feature_flag', false);
const welcomeText = config.getString('welcome_text', 'Welcome');
const maxItems = config.getNumber('max_items', 10);
const theme = config.getJson('theme_config', {});

fetchRemoteConfig() automatically includes:

• platform from SDK options
• appVersion from SDK appVersion
• buildNumber from SDK buildNumber
• profileId from identify(...)
• primitive global properties from setGlobalProperties(...) as userProperties
• language from SDK options or detected locale
• country from SDK options or detected locale region
• randomSeed from profileId or current session id

React Native additionally auto-fills:

• appVersion from the installed app version
• buildNumber from the installed build number