SDK Installation

Feature flag projects use npm SDK packages instead of a web snippet. Install @avsbhq/browser for vanilla JavaScript or @avsbhq/react for React applications.

JavaScript SDK (@avsbhq/browser)

Install the package

1npm install @avsbhq/browser

Initialize the client

Pass your environment-specific SDK key and any user attributes you want to use for targeting.

1import { AvsbClient } from '@avsbhq/browser';
2
3const client = new AvsbClient({
4  sdkKey: 'sdk_production_abc123',
5  attributes: {
6    userId: 'user_789',
7    plan: 'premium',
8    country: 'US',
9  },
10});
11
12await client.onReady();

Find your SDK key on the Environments page in your feature flag project. Each environment has a unique key.

Evaluate flags

Use getFlag()with a flag key and a default value. The default is returned if the flag doesn't exist or the SDK hasn't initialized yet.

1// Boolean flag
2const showNewCheckout = client.getFlag('new_checkout', false);
3
4// String flag
5const theme = client.getFlag('homepage_theme', 'default');
6
7// Number flag
8const timeout = client.getFlag('api_timeout', 30);
9
10// JSON flag
11const config = client.getFlag('pricing_config', {});

Track events (for A/B test rules)

When your flags have A/B test rules with metrics attached, track conversion events from your code.

1// Track a conversion
2client.track('purchase');
3
4// Track with revenue
5client.track('purchase', { revenue: 49.99 });
6
7// Track with custom properties
8client.track('signup', { plan: 'premium' });

Update attributes

If user attributes change (e.g., after login), call setAttributes() to re-evaluate flags.

1client.setAttributes({ plan: 'enterprise' });

Clean up

Call close() to stop polling and flush any pending events.

1client.close();

React SDK (@avsbhq/react)

Install the packages

1npm install @avsbhq/browser @avsbhq/react

Wrap your app with the provider

1import { AvsbProvider } from '@avsbhq/react';
2
3function App() {
4  return (
5    <AvsbProvider
6      sdkKey="sdk_production_abc123"
7      attributes={{ userId: 'user_789', plan: 'premium' }}
8    >
9      <YourApp />
10    </AvsbProvider>
11  );
12}

Use hooks in components

1import { useFlag, useFlagDetails, useTrack } from '@avsbhq/react';
2
3function CheckoutPage() {
4  // Get a flag value — re-renders when the value changes
5  const showNewCheckout = useFlag('new_checkout', false);
6  const theme = useFlag('homepage_theme', 'default');
7
8  // Get detailed evaluation info (for debugging)
9  const details = useFlagDetails('new_checkout');
10  // { value, variationKey, source, ruleId, ruleType, flagKey }
11
12  // Track events
13  const track = useTrack();
14  const handlePurchase = () => track('purchase', { revenue: 49.99 });
15
16  return showNewCheckout
17    ? <NewCheckout theme={theme} onPurchase={handlePurchase} />
18    : <OldCheckout />;
19}

Advanced Options

Polling Interval

The SDK polls for datafile updates every 60 seconds by default. You can change this or disable auto-refresh:

1const client = new AvsbClient({
2  sdkKey: 'sdk_production_abc123',
3  pollingInterval: 30000,  // 30 seconds
4  autoRefresh: true,       // default
5});

Custom User ID Attribute

By default, track() uses userId from your attributes as the visitor identifier. If your system uses a different attribute name, configure it at initialization:

1const client = new AvsbClient({
2  sdkKey: 'sdk_production_abc123',
3  attributes: { visitorHash: 'abc-123' },
4  userIdAttribute: 'visitorHash',
5});

Flag Change Listener

1const unsubscribe = client.onFlagChange((flagKey, newValue, oldValue) => {
2  console.log(`Flag ${flagKey} changed from ${oldValue} to ${newValue}`);
3});
4
5// Later: stop listening
6unsubscribe();

Get All Flags

Retrieve all current flag values as a map:

1const allFlags = client.getAllFlags();
2// { new_checkout: true, homepage_theme: 'blue', ... }

Bootstrap / SSR (Server-Side Rendering)

By default, the SDK fetches the datafile asynchronously on mount. Until it loads, useFlag() returns default values — causing a flash of default content on the first render.

To avoid this, pre-fetch the datafile on the server and pass it as a bootstrap prop. Flags then evaluate synchronously on the first render with no loading period.

Next.js App Router Pattern

Server Component — app/layout.tsx:

1import { fetchDatafile } from '@avsbhq/browser/server'
2import { Providers } from './providers'
3
4export default async function RootLayout({ children }: { children: React.ReactNode }) {
5  const datafile = await fetchDatafile('sdk_prod_abc123')
6
7  return (
8    <html lang="en">
9      <body>
10        <Providers datafile={datafile}>{children}</Providers>
11      </body>
12    </html>
13  )
14}

Client Component — app/providers.tsx:

1'use client'
2import { AvsbProvider } from '@avsbhq/react'
3import type { FlagDatafile } from '@avsbhq/react'
4
5export function Providers({
6  children,
7  datafile,
8}: {
9  children: React.ReactNode
10  datafile: FlagDatafile | null
11}) {
12  return (
13    <AvsbProvider
14      sdkKey="sdk_prod_abc123"
15      attributes={{ userId: 'user_789' }}
16      bootstrap={datafile ?? undefined}
17    >
18      {children}
19    </AvsbProvider>
20  )
21}

Bootstrap is optional — the SDK works without it. When omitted, flags evaluate after the async datafile fetch completes. Bootstrap eliminates the brief loading period.

fetchDatafile Options

You can customize the CDN host and request timeout:

1const datafile = await fetchDatafile('sdk_prod_abc123', {
2  cdnHost: 'https://your-custom-cdn.com',  // default: https://cdn.avsb.cloud
3  timeout: 3000,                             // default: 5000ms
4})

Custom CDN Host

By default, the SDK fetches the datafile from https://cdn.avsb.cloud. If you self-host datafiles behind your own CDN, pass a cdnHost option when constructing the client (or the provider):

1const client = new AvsbClient({
2  sdkKey: 'sdk_prod_abc123',
3  cdnHost: 'https://cdn.mycompany.com',  // default: https://cdn.avsb.cloud
4})

Connection Status

The SDK automatically sends a heartbeat to the platform after each successful datafile fetch. No configuration is needed — it uses the heartbeatEndpoint from the published datafile.

The flag detail page and environments page show connection status per environment:

Green — Connected: heartbeat received within the last 5 minutes
Yellow — Stale: last heartbeat is older than 5 minutes
Gray — Not connected: no heartbeat has been received