React SDK
The SDK is a client-side library designed to interact with the FeaturesFlow service, allowing developers to manage feature toggless and trigger events within their applications. This documentation provides an overview of the SDK's functionality, including initialization, retrieving feature toggles, and triggering events.
Compatibility
The React SDK uses Context API, which is available in React 16.3.0 and higher.
Installation
To install the SDK, you can use npm or yarn:
npm install @featuresflow/sdk-react
or
yarn add @featuresflow/sdk-react
API
Under this section you can find the API reference for the React SDK.
<FeaturesFlowProvider/>
The behavior of the SDK can be customized using config
object passed to FeaturesFlowProvider
as prop.
Property | Type | Description |
authenticationKey | string | The authentication key is a unique identifier that allows the SDK to authenticate with the FeaturesFlow service. You can find out more about SDK keys here. |
identifier | string | The identifier should be unique per user session. It allows the SDK to track user sessions and make sure that a given user receives the same treatment for a feature toggle during the same session. |
properties | Record<string, string> | The properties object allows you to provide values for targeting rules that you have defined in your feature toggle. They correspong to |
options | object (optional) | The options object allows you to customize the SDK's behavior. |
options.awaitFeatures | boolean | By default FeaturesFlowProvider will not display children until the SDK is initialized and feature toggles are loaded. If you want to render the application immediately and load feature toggles in the background, you can set this property to |
options.disabled | boolean | If you want to disable the SDK, you can set this property to |
options.prefetchedFeatures | Record<string, string> | If you want to provide prefetched feature toggles, you can set this property to an object containing feature toggle keys and their treatments. This is useful when you want to provide feature toggles from the server side. |
useFeatureToggle()
The useFeatureToggle
hook allows you to retrieve feature toggles from the FeaturesFlow service. It can only be used within FeaturesFlowProvider
component.
Parameter | Type | Description |
key | string | The feature toggle key is a unique identifier that allows the SDK to retrieve the treatment value for a given feature toggle. |
fallback | string (optional) | Optional parameter that is returned when the feature toggle is not found or when the SDK is not yet initialized. By default, the fallback value is set to |
Usage
Initialization
To initialize the SDK, you can use the FeaturesFlowProvider
component. This component takes a config
object as a prop, which should contain an authenticationKey
and an identifier
.
import { FeaturesFlowProvider } from '@featuresflow/sdk-react'
const App = () => {
const config = {
authenticationKey: 'your_auth_key',
identifier: 'your_identifier'
}
return (
<FeaturesFlowProvider config={config}>
{/* Your application components */}
</FeaturesFlowProvider>
)
}
export default App
Targeting rules
You can provide properties
to config object. These properties should corespond to targeting rules that you have defined in your feature toggle. This is a very powerful feature that allows you to target specific users or groups of users.
const config = {
authenticationKey: 'your_authentication_key',
identifier: 'your_identifier'
properties: {
countryCode: 'US',
}
};
Rendering strategy
By default, the SDK will render children of FeaturesFlowProvider
after the SDK is initialized. This means that the SDK will wait for the feature toggles to be loaded before rendering the application. If you want to render the application immediately and load feature toggles in the background, you can use the awaitFeatures
property.
const config = {
authenticationKey: 'your_authentication_key',
identifier: 'your_identifier',
options: {
awaitFeatures: false
}
};
The awaitFeatures
property is by default set to true.
Retrieving Feature Toggles
To retrieve feature toggless, you can use the useFeatureToggle
hook. This hook takes a feature toggle key as a parameter and returns a treatment value.
import { useFeatureToggle } from '@featuresflow/sdk-react'
type FeatureToggleTreatment = 'Version-A' | 'Version-B' | 'control';
const MyComponent = () => {
const treatment: FeatureToggleTreatment = useFeatureToggle('feature_toggle_key');
return (
<div>
{treatment === 'Version-A' ? <VersionA /> : <VersionB />}
</div>
)
}
Warning
We recommend to always provide a fallback
value when using the useFeatureToggle
hook.
Otherwise, remember to always cover control
treatment in your code. This treatment is returned when the feature toggle is not found or when the SDK is not yet initialized.
Each time you retrive a feature toggle, the SDK will also trigger the feature toggle render. This means that the SDK will send an event to FeaturesFlow service, incrementing traffic recieved for your feature toggle as well as treatment traffic.