JavaScript
@flagsync/js-sdk
is an isomorphic library capable of running on Node.js and web browsers. However, it is meant for single-user contexts in browser environments, such as mobile or desktop web applications.
Compatible with Node.js 16+ and ES5.
TypeScript is fully supported.
Note on Node.js
While this SDK is stable in Node.js 16+, this is to support uncommon, one-off cases where you may need to initialize feature flags for a single user server-side.
For server-side applications, including SSR web applications, we strongly recommend using the Node.js SDK.
Get your SDK key
To start, you'll first need to locate your SDK key, which is specific to an Environment (e.g. Test, Production, Staging, etc.)
SDK keys are found within your organization's workspace settings.
Your API requests are authenticated using SDK keys. Any request that doesn't include an SDK key will return an error.
Client-side SDK keys are safe to expose, and should be used for client-facing applications such as Web Browsers, whereas server-side SDKs can expose details of your flag rules, such as internal email addresses or user keys, and should never be made public.
Install the library
To connect to FlagSync from code, you'll need to install the SDK.
Getting started
Here's a simple example that shows the most basic usage of the SDK:
Initialize the FlagSync client
To initialize the FlagSync client, you'll need your SDK key, and core.key
, which is often a unique identifier, such as user ID or email.
Once instantiated, there are two ways to observe the readiness of the SDK: events and promises.
Events
The SDK_READY_FROM_STORE
event is useful for quickly loading flags from LocalStorage
in Web browser environments.
This event only fires when using the localstorage
storage type; the default is memory
.
Promises & async/await
The SDK has two methods that return a promise for initialization, waitForReady
and waitForReadyCanThrow
. The former is identical to the SDK_READY
event.
The other method, waitForReadyCanThrow
, will throw an error if the SDK fails to initialize. This may be helpful in certain situations.
All client-facing errors are normalized to FsServiceError
in the SDK.
Flag evaluation
The
flag
method retrieves the value of a feature flag identified by theflagKey
.This function evaluates the user context against individual targeting rules, percentage rollouts, and default variants to determine and return the appropriate feature flag variant for that specific user.
If the SDK is not ready, the method will return the default value, or control
if one is not provided.
A flag impression is automatically registered whenever the flag
function is called from the SDK.
Example Usage
Flag impressions are automatically registered when the flag
function is called.
Learn more about Events.
Submit events
Track user actions or events within the application with the track
function.
When you call the track
function to submit events, you can optionally provide key-value properties or a numeric eventValue
.
We'll discuss the differences below, and when you might choose one over the other.
Example (Page Load Time)
Say you're releasing a new feature and want to ensure page load times have not degraded. Or, you're testing some optimizations and want to validate that they've had a positive effect.
We'll use the eventValue
for this type of event.
First, you'll start by submitting an Event.
Later on, you may create a Metric called "Average Page Load Time" from the
page_load_time
event to harvest the values.Finally, you may link this metric with a feature flag in an Experiment to prove your hypothesis.
Learn about Metrics to see how they work alongside events.
Example (Purchase Events)
Say you're releasing a feature that you believe will increase the purchase amounts of your customers. Or, you're testing different discount amounts that you believe will increase the overall number of purchases.
You'll most likely want to track purchase events within your application along with the item purchased.
We'll use properties
for this type of event.
Later on, you may create a Metric called "Average Purchase Price per User" to harvest the
price
of items submitted with thepurchase_event
.Or, you may create a Metric called "Count of Discounts" to track the
discount
value.Finally, you may link these metrics with a feature flag in an Experiment to prove your hypothesis.
Learn about Metrics to see how they work alongside events.
Flag updates
When a change to a feature flag is made in the FlagSync dashboard, a server-side event (SSE) is sent from FlagSync servers to the SDK.
Value change propagation is on the order of milliseconds.
While the default synchronization method is SSE, you may opt to use polling instead, or disable synchronization entirely. You can control this with sync
option:
Listen for Updates
You can listen for updates using the SDK_UPDATE
event.
Custom Attributes
When initializing the factory, you can pass custom attributes about the user or user segment, which are automatically made available in the FlagSync Dashboard for individual targeting.
Create a targeting rule based on the group
attribute.
Bootstrapping
You can initialize the SDK with a set of flags using the bootstrap
configuration. This is useful for setting default values or for testing.
Storage
By default, flags are stored in memory, however when running in a Web Browser, you can opt to use LocalStorage
instead, which is useful for quickly loading the last state of your flags.
When initializing from LocalStorage
, the SDK_READY_FROM_STORE
event is fired when the flags have been loaded.
Emitted once the SDK has loaded flags from LocalStorage
.
Fires quickly since no network request is required.
This data may be stale, and should not be considered a replacement for the SDK_READY
event.
FsConfig
You can configure any of the following option arguments when initializing the FlagSyncFactory
.
Last updated