Web SDK | Documentation

The Web SDK is the recommended package for browser-based integrations. It supports page views, external link tracking, data-attribute capture, JavaScript error capture, session access, experiment assignment, and remote config.

Install

npm install @flash-analytics/web@2.2.0

pnpm add @flash-analytics/web@2.2.0

Initialize

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

const analytics = new FlashAnalytics({
  appId: 'YOUR_APP_ID',
  endpoint: 'https://api.flashanalytics.app',
  capturePageViews: true,
  captureExternalLinks: true,
  captureDataAttributes: true,
  captureErrors: true,
  captureVariants: true,
});

Auto capture

page_view via capturePageViews
link_out via captureExternalLinks
Custom click events via captureDataAttributes and fa-track
js_error and unhandled_promise_rejection via captureErrors
Experiment auto-assignment via captureVariants

Core APIs

analytics.identify({
  profileId: 'user-123',
  email: 'user@example.com',
});

await analytics.track('signup_completed', { plan: 'pro' });

analytics.setGlobalProperties({
  environment: 'production',
});

Experiments

Enable captureVariants to keep a local cache of assignments in sync automatically. On each new session all experiments are fetched; after identify() only profile-mode assignments are refreshed; on session expiry only session-mode entries are removed.

// 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);

// Manual assignment (always calls the API)
const assignments = await analytics.autoAssignExperiments();
const variant = await analytics.assignExperiment('checkout-cta');

Remote config

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

const featureEnabled = config.getBoolean('feature_flag', false);
const welcomeText = config.getString('welcome_text', 'Welcome');
const maxItems = config.getNumber('max_items', 10);

Session access

await analytics.track('page_view');

const session = analytics.getSession();

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

Script tag

<script>
  window.fa = window.fa || function () {
    var q = [];
    return new Proxy(function () {
      arguments.length && q.push([].slice.call(arguments));
    }, {
      get: function (_t, key) {
        return key === 'q' ? q : function () {
          q.push([key].concat([].slice.call(arguments)));
        };
      }
    });
  }();

  window.fa('init', {
    appId: 'YOUR_APP_ID',
    capturePageViews: true,
    captureErrors: true,
  });
</script>
<script src="https://dashboard.flashanalytics.app/fa1.js" defer async></script>