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

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 `properties` that you can create in `IF` and `IF-ELSE` blocks in your feature toggle's targeting rules.
`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 `false`. By default it is set to `true`.
`options.disabled`	boolean	If you want to disable the SDK, you can set this property to `true`. This is useful when you need to wait for cookies to be accepted and fetch the feature toggles later.
`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 `control`.

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.