React
This SDK wraps the JavaScript SDK for smoother integration with React applications. However, if you're building a non-React application for web browsers, you should use our JavaScript SDK instead.
@flagsync/react-sdk
relies on the React Context API (React 16.3+).TypeScript is fully supported.
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, and pass it to FlagSyncProvider
.
Similar to other context providers, you can place FlagSyncProvider
at the root of your application, or as low in the component tree as you need, assuming your flag retrievals are below that depth.
Flag evaluation (hooks)
Flag impression(s) are automatically registered whenever the useFlag
or useFlags
hook is called from the SDK.
The SDK uses memoization to ensure that renders provoked from outside FlagSync do not result in duplicate impressions.
useFlag
useFlag
The
useFlag
hook 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, either control
will be returned, or the defaultValue
if one is provided.
Example usage
useFlags
useFlags
The
useFlags
hook retrieves the values of all feature flags.This function evaluates the user context against individual targeting rules, percentage rollouts, and default variants to determine and return the appropriate feature flag variants for that specific user.
If the SDK is not ready, either control
will be returned, or the defaultValue
if one is provided.
Example usage
Flag evaluation (component-based)
Instead of hooks, an alternative has been provided in the form of the render props pattern.
Flag impression(s) are automatically registered whenever the FlagSyncFlag
or FlagSyncFlags
component is used.
The SDK uses memoization to ensure that renders provoked from outside FlagSync do not result in duplicate impressions.
<FlagSyncFlag />
<FlagSyncFlag />
Identical to
useFlag
.The
FlagSyncFlag
component retrieves the value of a feature flag identified by theflagKey
.This component 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, either control
will be returned, or the defaultValue
if one is provided.
Example usage
<FlagSyncFlags />
<FlagSyncFlags />
Identical to
useFlags
.The
FlagSyncFlags
component retrieves the values of all feature flags.This component evaluates the user context against individual targeting rules, percentage rollouts, and default variants to determine and return the appropriate feature flag variants for that specific user.
If the SDK is not ready, either control
will be returned, or the defaultValue
if one is provided.
Example usage
Submit events
Track user actions or events within the application with the useTrack
hook.
Per the type definitions below, if you choose to pass an eventKey
to useTrack
you are effectively binding the return function that that specific event.
Example usage
When you call the track
function to submit events, you can optionally provide key-value properties or a numeric eventValue
.
For more information on the track
function, check out the JavaScript SDK reference.
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.
Unlike the JavaScript SDK, there is no need to listen for events in the React SDK, any component using a useFlag
or useFlags
hook with re-render automatically, same with <FlagSyncFlag/>
and <FlagSyncFlags />
.
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
Custom Attributes
When initializing the config, 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 isReadyFromStore
value for useFlag
, useFlags
, <FlagSyncFlag />
, and <FlagSyncFlags />
will be true
once the flags have been loaded.
Occurs quickly since no network request is required.
This data may be stale, and should not be considered a replacement for the isReady
boolean.
FsConfig
You can configure any of the following option arguments when initializing the config object for <FlagSyncProvider />
.
Last updated