featureflow-javascript-sdk

Featureflow Javascript Client SDK

Get your Featureflow account at featureflow.io

Get Started

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

Alternatively to see featureflow running in action, you can run the example in this repo:

Clone this repository
Update example/src/index.js const FF_KEY = 'your-javascript-environment-sdk-key';
Run $ npm install and $ npm run example

Examples

Codepen: https://codepen.io/featureflow/pen/BboreK

Change Log

Please see CHANGELOG.

Installation

Using NPM

$ npm install --save featureflow-client

Using bower

$ bower install featureflow-client

Usage

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://cdn.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>

Quick start

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

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'
}

You can include user context information when you initialise featureflow, these attributes can be used in feature targeting rules:

var user = {
  id: 'user123',
  attributes:{
    tier: 'gold',
    country: 'australia',
      roles: ['role1', 'role3']
  }
};
var featureflow = Featureflow.init(FF_KEY, user);

Additional configuration can be set during init also. You can set offline mode for test environments or local development and provide a default set of feature values, for example:

var featureflow = Featureflow.init(FF_KEY, user, {
    offline: true,
    defaultFeatures: {
      'feature-1': 'on',
      'feature-2': 'red',
      'test': '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-id`

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 id directly into the request. Here are some examples of how you can do this:

Using HTTP Header: headers["X-Featureflow-Anonymous-Id"] = featureflow.getAnonymousId()
Adding a query param: '?ff-anonymousid='+featureflow.getAnonymousId()

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.getAnonymousId()`

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.resetAnonymousId()`

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 extra meta about the current user. Used to serve different features for specifically targeted attributes.

`config`

Property	Type	Default	Description
`streaming`	`boolean`	`false`	Set to `true` when calling `Featureflow.init(..., ..., config)` to listen for realtime updates via SSE
`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. 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.
`offline`	`boolean`	`false`	Set to `true` to run in offline mode, this is for testing purposes. Featureflow will not attempt and calls and will use the defaultFeatures values only

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.

Roadmap

Write documentation
Release to npm
Release to bower
Automate release to bower on npm prepublish
Automate release script to cdn on npm prepublish

Publishing

./deploy_prod_npm.sh
./deploy_prod_s3.sh

License

Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 133 Commits
.circleci		.circleci
_bower		_bower
example		example
flow		flow
scripts		scripts
src		src
test		test
.babelrc		.babelrc
.flowconfig		.flowconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
deploy_prod_npm.sh		deploy_prod_npm.sh
deploy_prod_s3.sh		deploy_prod_s3.sh
invbatch.json		invbatch.json
karma.conf.js		karma.conf.js
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tests.webpack.js		tests.webpack.js
webpack.config.js		webpack.config.js
yarn.lock		yarn.lock

License

featureflow/featureflow-javascript-sdk

Folders and files

Latest commit

History

Repository files navigation

featureflow-javascript-sdk

Get Started

Examples

Change Log

Installation

Usage

Adding Featureflow

Webpack

Bower

CDN

Realtime events and EventSource

Quick start

Anonymous User and Featureflow Server SDKs

1. Access the cookie ff-anonymous-id

2. Pass the value into the request yourself

API and Configuration

Globals

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

featureflow.evaluate(featureKey)

featureflow.evaluate(featureKey).is(value)

featureflow.evaluate(featureKey).isOn()

featureflow.evaluate(featureKey).isOff()

featureflow.evaluate(featureKey).value()

featureflow.goal(goalKey)

featureflow.updateUser(user, [callback])

featureflow.getFeatures()

featureflow.getUser()

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

featureflow.off(event, [callback])

featureflow.getAnonymousId()

featureflow.hasReceivedInitialResponse()

featureflow.resetAnonymousId()

Object Types

user

config

Events

Featureflow.events.LOADED_FROM_CACHE

Featureflow.events.INIT

Featureflow.events.LOADED

Featureflow.events.UPDATED_FEATURE

Featureflow.events.ERROR

Roadmap

Publishing

License

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Languages

1. Access the cookie `ff-anonymous-id`

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

`featureflow.evaluate(featureKey)`

`featureflow.evaluate(featureKey).is(value)`

`featureflow.evaluate(featureKey).isOn()`

`featureflow.evaluate(featureKey).isOff()`

`featureflow.evaluate(featureKey).value()`

`featureflow.goal(goalKey)`

`featureflow.updateUser(user, [callback])`

`featureflow.getFeatures()`

`featureflow.getUser()`

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

`featureflow.off(event, [callback])`

`featureflow.getAnonymousId()`

`featureflow.hasReceivedInitialResponse()`

`featureflow.resetAnonymousId()`

`user`

`config`

`Featureflow.events.LOADED_FROM_CACHE`

`Featureflow.events.INIT`

`Featureflow.events.LOADED`

`Featureflow.events.UPDATED_FEATURE`

`Featureflow.events.ERROR`

Packages