Floodgate Docs

JavaScript SDK Documentation

The guide will walk you through the installation and usage of the Floodgate JavaScript SDK.

Requirements The JavaScript SDK is designed to run on the clients browser and is not intended for use with Node.js or Server Side Rendering. If you require such use please take a look at the Node.js SDK.

Getting Started

The first step is to install the Floodgate SDK as a dependency in your application using your application's dependency manager.

npm i floodgate-javascript-sdk

Next import the package into your application.

import * as floodgate from "floodgate-javascript-sdk";
// or
const floodgate = require('floodgate-javascript-sdk');


Alternatively you can use the SDK via the CDN

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/dist/floodgate.min.js"></script>

Now you have the Floodgate SDK installed and imported you can create a new instance of the Floodgate Client.

const floodgateClient = floodgate.createClient("ENTER-YOUR-SDK-KEY");

Evaluating a Flag

KeyYesThis is the Flag Key which you entered when creating the flag.
Default ValueYesThis is the value which you want the flag to evaluate to if no flag data can be found.
User ObjectNoThis is an optional value which can be passed containing information about the user. This information is required to evaluate flags when doing user targeting or percentage rollout releases.

The example below shows an evaluation of a flag called buy-now-button-colour passing in a default value of orange. We are then going to dynamically change the background colour of a button with the Id of buy-now.

client.on('ready', function() {
const colour = floodgateClient.GetValue('buy-now-button-colour', 'orange');
document.getElementById('buy-now').style.backgroundColor = colour;

Client Events The Floodgate Client object will emit a ready event once the client has loaded the flag configuration data. We wait for the ready event and then evaluate the flag. This ensures we have all the required data available to be able to evaluate the flag accordingly. You can also use the asynchronous method FetchValue which accepts a callback method if you don't want to use events.

Customising the Floodgate Client

The Floodgate Client offers the following customisation options to help with your implementation.

refreshIntervalThe Floodgate Client stores and evaluates your flag configurations locally. From time-to-time the client will request an update from the server to make sure it always has the most up-to-date flag configuration data. By default this happens every 60 seconds. You can override this value using the RefreshInterval setting. The RefreshInterval expressed in seconds.

In the example below we are setting the RefreshInterval to 5 seconds.

const config = {
refreshInterval: 10
const floodgateClient = floodgate.createAutoUpdateClient("ENTER-YOUR-SDK-KEY", config);

Targeting users with the User Object

User targeting is a key aspect of getting the most benefit out of using feature flags. By defining users we are able to take advantage of features like user targeting and percentage rollouts (canary releases).

Security and User Data Even though Floodgate requires data about your users to allow for targeted flag evaluations, this data is never sent to the Floodgate servers. All evaluations are done locally on your servers within your application.

User Object

User IdYesStringEvery user is required to be assigned a unique id. This could be a database id or the users email address for example. Session IDs or UUIDs are suited best.
Email NoStringYou can optionally set the users email address if you would like to evaluate against specific users emails.
Custom AttributesNoJsonEach user can have any number of custom attibutes assigned to them. This is a very powerful feature of Floodgate as it gives you the flexability to evaluate flags against any data element that may belong to your users.

Below is an example of creating a Floodgate User Object.

const customAttributes = {
name: "Peter Parker",
subscription: "Gold",
country: "UK",
role: "Admin"
const user = floodgate.createUser("a-unique-id", "[email protected]", customAttributes);

Once we have created the User Object we can pass this into the GetValue method to have the flag evaluated specifically for the user as shown below.

const colour = floodgateClient.GetValue('buy-now-button-colour', 'orange', user);

View the Code

All our SDKs are open source and you are free to check out what's going on inside them. In fact we encourage contributions from the Floodgate community. You can view the source code on GitHub.