Flagship - REACT SDK

React Flagship SDK provides a <FlagshipProvider />, which makes Flagship features available to the rest of your app. Flagship features are accessible using Flagship hooks, have a look to the documentation for details.

Prerequisites

• Node.js: version 6.0.0 or later...

• Npm: version 5.2.0 or later...

• React: version 16.8.0 or later... (This SDK supports only hooks for now)

Good to know

- Typescript supported ✅

- Small dev demo app but more to come soon! 👨‍💻

Getting Started

1. Install the node module:

npm install @flagship.io/react-sdk

2. Import the Flagship React provider at the root level of your app like App.js file :

import React from "react";
import { FlagshipProvider } from "@flagship.io/react-sdk";

const App = () => (
  <>
    <FlagshipProvider>
      {/* [...] */}
    </FlagshipProvider>
  </>
);

3. Initialize the provider with at least required props such as envId, visitorData :

import React from "react";
import { FlagshipProvider } from "@flagship.io/react-sdk";

const App = () => (
  <>
    <FlagshipProvider
      envId="bn1ab7m56qolupi5sa0g"
      visitorData={{
        id: "test-visitor-id",
        context: {},
      }}
      config={{
        fetchNow: true,
        enableConsoleLogs: true,
      }}
    >
      {/* [...] */}
    </FlagshipProvider>
  </>
);

4. Use a Flagship hook in a component. In most case, you'll want to have modifications in cache :

import React from 'react';
import { useFsModifications } from "@flagship.io/react-sdk";

export const MyReactComponent = () => {
  const fsModifications = useFsModifications([
    {
      key: "backgroundColor",
      defaultValue: "green",
      activate: false,
    },
  ]);
  return (
      <div
        style={{
          height: "200px",
          width: "200px",
          backgroundColor: fsModifications.backgroundColor,
        }}
      >
        {"I'm a square with color=" + fsModifications.backgroundColor}
      </div>
  )
}

FlagshipProvider Props

This is all available props which you can use inside the FlagshipProvider react component:

Props	Type	Default	Description
envId	string	*required*	Your Flagship environment id.
visitorData	object	*required*	This is the data to identify the current visitor using your app. The visitorData object takes the following attributes: Argument Type Description id string Required. The id of the visitor context object Optional. Your Flagship visitor context. You'll set inside attributes which should match those defined in your campaigns.
config	object	{}	This is the settings of the SDK. It takes an object which is the same shape as the JS SDK settings. Go have a look, there are many options. 🙂
onInitStart	function():void	null	Callback function called when the SDK starts initialization.
onInitDone	function():void	null	Callback function called when the SDK ends initialization.
onUpdate	function():void	null	Callback function called when the SDK is updated. For example, after a synchronize is triggered or visitor context has changed.
onSavingModificationsInCache	function(obj):void	null	Callback function called when the SDK is saving modifications in cache. It has an argument which has the following shape: Key/Property Description modifications It is an object which contains modifications past and future computed modifications. Key/Property Description before Modificaitons previously in cache. after New modificaitons which are about to be saved in cache. saveInCacheModifications This is a function which you'll have to call if you want to override the modifications which will be saved in the SDK cache. It has one argument which the modifications that you want to override. If you leave it undefined, it will keep default behavior.
defaultModifications	object	null	This is an object which has the shape of Flagship modifications as it is return from the Flagship API. Can be useful when you already manually fetched the data before or you have your own cache. Providing this props avoid the SDK to have an empty cache during first initialization. The default modifications provided will be override once the SDK finish to fetch Flagship API with an initialization or a synchronization.
loadingComponent	React.ReactNode	undefined	This is component which will be render when Flagship is loading on first initialization only. By default, the value is undefined which means it will display your app and it might display default modifications value for a very short moment.

Flagship Hooks

Here the list of current available hooks:

• useFlagship
• useFsModifications
• useFsActivate
• useFsSynchronize

useFlagship

Most used hook from the Flagship React SDK. Through this hook, you can access to modifications of your current visitor and have an access to the SDK status.

returns an object (Typescript: UseFlagshipOutput)

Argument	Type	Default	description
params	object (TS:UseFlagshipOutput)	*required*	Contains further required nodes. See the shape of this object just below.

useFlagship parameters

Argument	Type	description
modifications	Object	Node param to specify flagship modifications: Argument Description requested Required. An array of object for each modifications and follow this shape: Argument Description key Required. The name of the modification. defaultValue Required. The default value if no value for this modification is found. activate Optional. activateAll Optional. The value is false by default
status	Object	Gives you some informations about SDK current sate: Key/Property Description isLoading If true, the SDK it not ready, false otherwise. lastRefresh Date cast string with ISO format. This is the date corresponding to the most recent moment where modifications were saved in cache.

useFsModifications

This will give you the modification saved in the SDK cache.

NOTE: If the SDK cache is empty, you can expect that it will return nothing.

returns Flagship modifications

Argument	Type	Default	description
modificationsRequested	Array(object)	*required*	List of all modifications you're looking for. Each element of the array follow this object structure: Argument Description key Required. The name of the modification. defaultValue Required. The default value if no value for this modification is found. activate Optional.
activateAllModifications	Boolean	false	If set to true, all modifications will be activated. If set to false, none will be activated. Be aware that if this argument is set, the attribute activate set in each element of array modificationsRequested will be ignored.

Demo:

• coming soon

useFsActivate

return void

Argument	Type	Default	description
modificationKeys	Array(string)	*required*	An array of modification key. For each key, a http will be done to trigger the activate of corresponding modification.
applyEffectScope	Array(string)	[]	This argument has same behavior as React.useEffect (2nd argument) hook. It will listen values inside array and trigger a synchronize if one them has changed. By default it is trigger once, during React component where it's used, did mount.

Demo:

• coming soon

useFsSynchronize

Refresh modifications in cache by making a http request to the Flagship API.

return void

Argument	Type	Default	description
applyEffectScope	Array(string)	[]	This argument has same behavior as React.useEffect (2nd argument) hook. It will listen values inside array and trigger a synchronize if one them has changed. By default it is trigger once, during React component where it's used, did mount.
activateAllModifications	Boolean	false	If set to true, all modifications will be activated. If set to false (default behavior), none will be activated.

Demo:

• coming soon

Contributing

Take a look to the Contributors Guide.

What is Flagship ?

Have a look here.

License

Flagship uses license under the Apache version 2.0.