@featurevisor/sdk

@featurevisor/sdk

Universal JavaScript SDK for both Node.js and the browser.

Visit https://featurevisor.com/docs/sdks/ for more information.

• Installation
• Usage
• Options
  • bucketKeySeparator
  • configureBucketKey
  • configureBucketValue
  • datafile
  • datafileUrl
  • handleDatafileFetch
  • initialFeatures
  • interceptContext
  • logger
  • onActivation
  • onReady
  • onRefresh
  • onUpdate
  • refreshInterval
  • stickyFeatures
• API
  • isEnabled
  • getVariation
  • getVariable
  • activate
  • isReady
  • refresh
  • setLogLevels
  • on
  • addListener
  • off
  • removeListener
  • removeAllListeners
  • onReady

Installation

$ npm install --save @featurevisor/sdk

Usage

Initialize the SDK:

import { createInstance } from "@featurevisor/sdk";

const sdk = createInstance(options);

Options

Options you can pass when creating Featurevisor SDK instance:

bucketKeySeparator

• Type: string
• Required: no
• Defaults to: .

configureBucketKey

• Type: function
• Required: no

Use it to take over bucketing key generation process.

const sdk = createInstance({
  configureBucketKey: (feature, context, bucketKey) => {
    return bucketKey;
  }
});

configureBucketValue

• Type: function
• Required: no

Use it to take over bucketing process.

const sdk = createInstance({
  configureBucketValue: (feature, context, bucketValue) => {
    return bucketValue; // 0 to 100,000
  }
});

datafile

• Type: object
• Required: either datafile or datafileUrl is required

Use it to pass the datafile object directly.

datafileUrl

• Type: string
• Required: either datafile or datafileUrl is required

Use it to pass the URL to fetch the datafile from.

handleDatafileFetch

• Type: function
• Required: no

Pass this function if you need to take over the datafile fetching and parsing process:

const sdk = createInstance({
  handleDatafileFetch: async (datafileUrl) => {
    const response = await fetch(datafileUrl);
    const datafile = await response.json();

    return datafile;
  }
});

initialFeatures

• Type: object
• Required: no

Pass set of initial features with their variation and (optional) variables that you want the SDK to return until the datafile is fetched and parsed:

const sdk = createInstance({
  initialFeatures: {
    myFeatureKey: {
      enabled: true,

      // optional
      variation: "treatment",
      variables: {
        myVariableKey: "my-variable-value"
      }
    }
  }
});

interceptContext

• Type: function
• Required: no

Intercept given context before they are used to bucket the user:

const defaultContext = {
  platform: "web",
  locale: "en-US",
  country: "US",
  timezone: "America/New_York",
  userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko)",
};

const sdk = createInstance({
  interceptContext: (context) => {
    return {
      ...defaultContext,
      ...context,
    };
  }
});

logger

• Type: object
• Required: no

Pass a custom logger with custom levels, otherwise it the SDK will print logs to the console for error and warn levels.

import { createInstance, createLogger } from "@featurevisor/sdk";

const sdk = createInstance({
  logger: createLogger({
    levels: ["debug", "info", "warn", "error"],
    handler: (level, message, details) => {
      // do something with the log
    },
  }),
});

onActivation

• Type: function
• Required: no

Capture activated features along with their evaluated variation:

const sdk = createInstance({
  onActivation: (featureKey, variation, context, captureContext) => {
    // do something with the activated feature
  }
});

captureContext will only contain attributes that are marked as capture: true in the Attributes' YAML files.

onReady

• Type: function
• Required: no

Triggered maximum once when the SDK is ready to be used.

const sdk = createInstance({
  onReady: () => {
    // do something when the SDK is ready
  }
});

onRefresh

• Type: function
• Required: no

Triggered every time the datafile is refreshed.

Works only when datafileUrl and refreshInterval are set.

const sdk = createInstance({
  onRefresh: () => {
    // do something when the datafile is refreshed
  }
});

onUpdate

• Type: function
• Required: no

Triggered every time the datafile is refreshed, and the newly fetched datafile is detected to have different content than last fetched one.

Works only when datafileUrl and refreshInterval are set.

const sdk = createInstance({
  onUpdate: () => {
    // do something when the datafile is updated
  }
});

refreshInterval

• Type: number (in seconds)
• Required: no

Set the interval to refresh the datafile.

const sdk = createInstance({
  refreshInterval: 60 * 5, // every 5 minutes
});

stickyFeatures

• Type: object
• Required: no

If set, the SDK will skip evaluating the datafile and return variation and variable results from this object instead.

If a feature key is not present in this object, the SDK will continue to evaluate the datafile.

const sdk = createInstance({
  stickyFeatures: {
    myFeatureKey: {
      enabled: true,

      // optional
      variation: "treatment",
      variables: {
        myVariableKey: "my-variable-value"
      }
    }
  }
});

API

These methods are available once the SDK instance is created:

isEnabled

isEnabled(featureKey: string, context: Context): boolean

getVariation

getVariation(featureKey: string, context: Context): VariationValue

getVariable

getVariable(featureKey: string, variableKey: string, context: Context): VariableValue

Also supports additional type specific methods:

• getVariableBoolean
• getVariableString
• getVariableInteger
• getVariableDouble
• getVariableArray
• getVariableObject
• getVariableJSON

activate

activate(featureKey: string, context: Context): VariationValue

Same as getVariation, but also calls the onActivation callback.

This is a convenience method meant to be called when you know the User has been exposed to your Feature, and you also want to track the activation.

isReady

isReady(): boolean

Synchonously check if the SDK is ready to be used.

refresh

refresh(): void

Manually refresh datafile.

setLogLevels

setLogLevels(levels: LogLevel[]): void

Accepted values for levels: ["debug", "info", "warn", "error"].

on

on(event: string, callback: function): void

Listen to SDK events, like:

• ready
• activation
• refresh
• update

addListener

Alias for on method.

off

off(event: string, callback: function): void

removeListener

Alias for off method.

removeAllListeners

removeAllListeners(event?: string): void

onReady

Resolves the SDK instance with a promise for convenience when it's ready:

onReady(): Promise

License

MIT © Fahad Heylaal

Changelog

1.29.2 (2025-01-25)

Note: Version bump only for package featurevisor