featureflow

The featureflow Developer Hub

Welcome to the featureflow developer hub. You'll find comprehensive guides and documentation to help you start working with featureflow as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Javascript SDK

Get Started

The easiest way to get started is to follow the Featureflow quick start guides

Alternatively clone this repository and run $ npm install and $ npm run example

Change Log

Please see CHANGELOG.

Installation

Using NPM

$ npm install --save featureflow-client

Using bower

$ bower install featureflow-client

Adding Featureflow

Webpack

If you are using webpack, you can require the code using

var Featureflow = require('featureflow-client');

or using es6 syntax

import Featureflow from 'featureflow-client';
Bower

Include the following script in HTML file. This will expose the global variable Featureflow

<script crossorigin="anonymous" src="bower_components/featureflow-client/dist/featureflow.min.js"></script>

Note: It is recommended to use build tools to manage your bower dependencies.
Please see the bower website for more details.

CDN

Include the following script in HTML file. This will expose the global variable Featureflow

<script crossorigin="anonymous" src="https://features.featureflow.io/featureflow.js"></script>
Realtime events and EventSource

Featureflow uses EventSource for realtime streaming of feature updates. If you wish to target a browser that doesn't natively support EventSource, we recommend using a polyfill such as this one.

You can either require/include the polyfill in your application,

//for example
import 'event-source-polyfill';

or include it in your <head> of your html file before you load the Featureflow client.

<script src="https://cdnjs.cloudflare.com/ajax/libs/event-source-polyfill/0.0.9/eventsource.js"></script>

Initialising Featureflow

Get your environment's Featureflow Javascript API key and initialise a new Featureflow client

var FF_JS_API_KEY = '<Your javascript api key goes here>';
//...
var featureflow = Featureflow.init(FF_JS_API_KEY);

This will load the value of each feature for the current environment specified by the api key. These values can be toggled on and off at https://<your-org-key>.featureflow.io

Note: You are responsible for passing the featureflow client instance around your application

Evaluate a feature

In your code, you can test the value of your feature where the value of my-feature-key is equal to 'on'

if (featureflow.evaluate('my-feature-key').is('on')){
  // this feature code will be run because 'my-feature-key' is set to 'on'
}

Because the default variants for any feature are 'on' and 'off', we have provided two helper methods .isOn() and .isOff()

if(featureflow.evaluate('my-feature-key').isOn()){
  // this feature code will be run because 'my-feature-key' is set to 'on'
}

if(featureflow.evaluate('my-feature-key').isOff()){
  // this feature code won't be run because 'my-feature-key' is not set to 'off'
}

Further documentation can be found here

Anonymous User and Featureflow Server SDKs

In some instances you will want to split test a feature with anonymous users that spans both client and server code.
The featureflow client generates a unique anonymous key for the user which can be shared with your server requests.
There are a couple of ways you can do this.

1. Access the cookie ff-anonymous-key

Anytime the anonymous user is updated the featureflow client will set the ff-anonymous-id cookie.
If request server is on the same [sub]domain and it doesn't have a user id you should use this cookie.

2. Pass the value into the request yourself

If you cannot use cookies (e.g. api on a separate [sub]domain), you can pass the anonymous key directly into the request.
Here are some examples of how you can do this:

  1. Using HTTP Header: headers["X-Featureflow-Anonymous-Key"] = featureflow.getAnonymousKey()
  2. Adding a query param: '?ff-anonymouskey='+featureflow.getAnonymousKey()

Update the user when a user logs in

Typically you would want to update the user information when a user logs in or out of your web site. You can do this with the 'featureflow.updateUser()' method

var u = myLoggedInUser; //on return from your login function
var user = {
	id: u.id
  attributes:{    
		tier: u.tier, //eg. 'gold'
		country: u.country, //eg 'UK'
		organisation: u.organisationId, //e.g '1234567'
		language: 'en_GB'
	}
};
featureflow.updateUser(user);

when the user logs out, clear the user, either call:
featureflow.updateUser();
or you may wish to reset to an anonymous user with other values.

API and Configuration

Globals

Featureflow.init(apiKey, [user], [config])

Returns a featureflow instance, see below

Params Type Default Description
apiKey* string Required The Featureflow Javascript API key for the environment or project you are targeting
user user See the user object below
config config See the config object below
return featureflow See Featureflow Instance below

Featureflow Instance

These properties are available on the return of Featureflow.init(...)

featureflow.evaluate(featureKey)

Returns an object that can be used to help evaluate feature values in an expressive way.

featureflow.evaluate(featureKey).is(value)

Evaluates the value of a feature for the given user.

Params Type Default Description
featureKey* string Required The feature key you are targeting
value* string Required The value you are testing against
return boolean true if the feature's value is equal to the value provided, otherwise false
featureflow.evaluate(featureKey).isOn()

Evaluates the value of a feature for the given user is equal to 'on'.

Params Type Default Description
featureKey* string Required The feature key you are targeting
return boolean true if the feature's value is equal to 'on' provided, otherwise false
featureflow.evaluate(featureKey).isOff()

Evaluates the value of a feature for the given user is equal to 'off'.

Params Type Default Description
featureKey* string Required The feature key you are targeting
return boolean true if the feature's value is equal to 'off' provided, otherwise false
featureflow.evaluate(featureKey).value()

Returns the value of a feature for the given user.

Params Type Default Description
featureKey* string Required The feature key you are targeting
return string The value of the feature, or the default feature value from config.defaultFeatures[featureKey] if present, or 'off'

featureflow.goal(goalKey)

Sends a goal event, along with the current evaluated features to featureflow.io. Use with experiments in the admin console.

Params Type Default Description
goalKey* string The key of the goal you want to target.

featureflow.updateUser(user, [callback])

Updates the current user of the instance and reevaluates all feature features using the new user.

Params Type Default Description
user user ... See the user object below

Fires a Featureflow.events.LOADED event when the features have been evaluated.
Also Fires the callback if provided with the newly evaluated features.

featureflow.getFeatures()

Returns the current evaluated features as flat key-value map

Params Type Default Description
return object The current features object

featureflow.getUser()

Returns the current user

Params Type Default Description
return user The current user

featureflow.on(event, callback, [bindContext])

Listen to events when the featureflow instance is updated

Params Type Default Description
event* string Required The name of the event to subscribe to. See Events section below for available events.
callback* function Required The function to call when the event is emitted.
bindContext any undefined The context to bind the event callback to.

featureflow.off(event, [callback])

Listen to events when the featureflow instance is updated

Params Type Default Description
event* string Required The name of the event to unsubscribe from.
callback function Required The callback used when binding the object

featureflow.getAnonymousKey()

Returns the anonymous user id assigned for the user in localStorage.

Params Type Default Description
return string The string of the anonymous user id in localStorage.

featureflow.hasReceivedInitialResponse()

Returns true if an initial response has been returned from the server, regardless of the status code.

Params Type Default Description
return boolean false true if the initial request to featureflow has completed

featureflow.resetAnonymousKey()

Resets the anonymous user id for the user stored in localStorage. This will not re-evaluate the features, you must still call updateUser() to evaluate the latest features variants.

Params Type Default Description
return string The string of the new anonymous user id.

Object Types

user

Property Type Default Description
id string 'anonymous:**********' Uniquely identifies the current user. Also used to calculate split variants. If not provided a random string prefixed with 'anonymous:' will be used. This will set a cookie that can be used to link the anonymous user with your server's Featureflow SDK.
attributes object undefined Flat key-value object containing attributes about the current user. Used to serve different features for specifically targeted attributes.

config

Property Type Default Description
streaming boolean true Set to true when calling Featureflow.init(..., ..., config) to listen for realtime updates
useCookies boolean true Set to false if you do not want to use cookies (you will have to pass the result of featureflow.getAnonymousId() to any future requests if you wish for the server to match the client anonymous key)
defaultFeatures object undefined A flat key-value object representing the default variants a feature should be set to if there is an interrupted connection and no cached value. <br/> <br/> e.g. if you set config.defaultFeatures to {'my-feature': 'on'}, featureflow.evaluate('my-feature').isOn() will return true when there is an interrupted connection to Featureflow and no locally cached feature features.

Events

Featureflow.events.LOADED_FROM_CACHE

Fired when features have been loaded from localstorage.
Triggered by both Featureflow.init(...) and featureflow.updateUser.

Callback is fired with one parameter with the value of all evaluated features.

Featureflow.events.INIT

Fired when features have been evaluated and loaded.
Triggered by both Featureflow.init(...) and featureflow.updateUser.

Callback is fired with one parameter with the value of all evaluated features.

Featureflow.events.LOADED

Deprecated: Use Featureflow.events.INIT instead.

Featureflow.events.UPDATED_FEATURE

Only available when streaming is enabled.
Fired when a feature has been changed.

Callback is fired with one parameter with the value of only the updated features returned by the stream. In the majority of cases, this object will only contain one property.

Featureflow.events.ERROR

Fired when an error has occurred evaluating the feature features for the given user.

Callback is fired with one parameter with the error message.

Please see our github documentation for SDK Reference: https://github.com/featureflow/featureflow-javascript-sdk

Javascript SDK