Koople
  • Getting Started
  • Core Concepts
  • Using Koople
    • First steps
    • Release Toggles
      • Long-Live/Release toggles
    • Remote Config
    • Target Groups
    • Users
    • Flag references
    • Audit Log
    • Member Permissions
    • Environment Settings
    • API Keys
    • Plans
  • SDK Reference
    • JavaScript
    • React
    • C#
    • Java
  • Api Reference
    • Client (WIP)
    • Server (WIP)
  • Changelog
Powered by GitBook
On this page
  • Getting Started
  • Customize the SDK
  • Storage
  • Boot run
  • Fallback
  • Timeout
  • Polling interval
  • Events
  • onReady
  • onIdentified
  • onChanges
  • Methods
  • releaseToggles
  • isEnabled
  • remoteConfigs
  • valueOf
  • evaluation
  • identify
  • refresh
  • User object
  • Evaluation object
  • Anatomy
  • Example

Was this helpful?

  1. SDK Reference

JavaScript

PreviousPlansNextReact

Last updated 4 years ago

Was this helpful?

Getting Started

If still not registered, sign up and create an account at .

1. Install and import package

npm i @pataflags/sdk-js

Refer to the release page to identify the latest version.

2. Initialize the SDK

const user = { id: 'aUserId' }
const pfclient = PFClient.initialize('YOUR_API_KEY', user);

3. Get your values

pfclient.onReady(() => {
    const isEnabled = pfclient.isEnabled('myAwesomeFeature');
    if (isEnabled) {
        // Show the feature
    } else {
        // Hide the feature
    }
});

Customize the SDK

You can set custom parameters to the client by creating a custom configuration object:

const options = { timeout: 500 };
const pfclient = PFClient.initialize('YOUR_API_KEY', user, options);

Parameter

Description

Default

storage

none

bootRun

network

fallback

null

timeout

2000

pollingInterval

0

Storage

Value

Behaviour

none

session

persistent

const pfclient = PFClient.initialize('YOUR_API_KEY', user, { 
    storage: 'persistent'
});

Boot run

Value

Behaviour

network

The default value. The SDK will boot from the server response.

storage

const pfclient = PFClient.initialize('YOUR_API_KEY', user, {
    bootRun: 'storage' 
});

Fallback

Use fallback to provide a default evaluation object for the SDK. When the request fails, and the storage is empty, the fallback will be returned. If the SDK has already initialized successfully, the fallback will not take effect.

const pfclient = PFClient.initialize('YOUR_API_KEY', user, { 
    fallback: YOUR_EVALUATION_OBJECT
});

Alternatively, you can provide your fallback from storage. This means that in case of failure, the last valid server configuration will be returned.

Timeout

const pfclient = PFClient.initialize('YOUR_API_KEY', user, {
    timeout: 50 
});

Polling interval

The minimum value is 1 second. If the value is less than 1 it will be ignored and automatically set to 1.

const pfclient = PFClient.initialize('YOUR_API_KEY', user, {
    pollingInterval: 60 
});
pfclient.onChanges(() => {
    // ...
});

Events

onReady

The SDK will raise the ready event when the SDK is initialized.

The initialization will depend on the SDK configuration. If you have configured the bootRun parameter as storage, the initialization will be immediate. Else it will take until the server responds.

You can subscribe to the ready event before or after the SDK initialization, in both cases, the callback will be executed.

pfclient.onReady(() => { 
    const isEnabled = pfclient.releaseToggle('myAwesomeFeature');
    if (isEnabled) {
        // Show the feature
    } else {
        // Hide the feature
    }
});

onIdentified

pfclient.onIdentified(() => { 
    // ...
});

onChanges

In some cases, you can use changes event as a mechanism to ask the user if wants to apply changes or reload the page.

pfclient.onChanges(() => { 
    if (confirm('There is a more updated version of the page.' +
        'Do you want to reload the page?')) {
        // apply changes or reload page
    }
});

Methods

releaseToggles

The releaseToggles method will return a map of release toggles with its settings.

pfclient.releaseToggles();

isEnabled

The isEnabled method will return a boolean indicating whether a release toggle is enabled or disabled.

Name

Type

releaseToggleKey

string

required

pfclient.isEnabled('myAwesomeFeature');

remoteConfigs

The remoteConfigs method will return a map of remote configs with its settings.

pfclient.remoteConfigs();

valueOf

The valueOf method will return a value for a remote config. You can pass an optional second parameter used as a fallback if there is no value.

Name

Type

remoteConfigKey

string

required

fallback

string

optional

pfclient.valueOf('theme', 'light');

evaluation

pfclient.evaluation();

identify

Changes will be listened from onIdentified and onChanges.

Name

Type

user

required

client.onIdentified(() => { /* UPDATED SETTINGS */ });
client.onChanges(() => { /* UPDATED SETTINGS */ });

client.identify({ id: 'logged-user' });

refresh

Changes can be listened from onChanges.

client.onChanges(() => { /* UPDATED SETTINGS */ });

client.refresh();

User object

// TODO ...

Evaluation object

Anatomy

A valid evaluation object should contain these fields:

Name

Description

releaseToggles

Is a map of key values.

  • The keys represent the key of your release toggle and should be a string.

  • The values indicate if your release toggle is enabled or disabled and should be a boolean.

remoteConfigs

Is a map of key values.

  • The keys represent the key of your remote config and should be a string.

  • The values indicate a value of your remote config and should be a boolean.

Example

const evaluationObject = {
    releaseToggles: {
        myAwesomeFeature: true,
        mySuperFeature: true
    },
    remoteConfigs: {
        theme: 'dark',
        permissions: 'ADMIN'
    }
};

Use storage to keep your response in the cache. See .

Use bootRun to provide an initial for the SDK. See .

Use fallback to provide a default evaluation object to the SDK. See .

The number of milliseconds the SDK waits for a response from the Koople servers before returning the from the storage or fallback. See .

Interval in seconds with which the SDK makes requests to the server to update the settings. See .

Use storage to keep your response in the cache. When the request fails, the SDK try automatically to get the latest valid from storage.

Default value. The SDK will not store the .

The SDK will store the latest between page loads.

The SDK will store the latest between sessions.

UsebootRun to provide an initial for the SDK.

The SDK will boot with the lastest stored response. Meanwhile, the request is loading in the background, and the will be updated with the new server response. This mode allows loading the page without any delay.

The number of milliseconds the SDK waits for a response from the Koople servers before returning the from the storage or fallback.

Timeout is more useful when combines with fallback. The minimum value timeout is 50 milliseconds. If the value is less than 50 it will be ignored and automatically set to 50. If you want less than 50 milliseconds, then see .

You can configure your SDK to update the every pollingInterval seconds automatically. You will receive the changes in the subscription to onChanges.

The SDK will raise the identified event when you call to method.

While the ready and identified events are fired only once, changes will be fired every time the is updated, including the times ready and identified events are fired.

Changes event can cause that, if the changes, the page will be repainted or cause UI flickering.

The evaluation method will return an .

The identify method provides a mechanism to update your when the user has changed. It's the typical login scenario when a user goes from being anonymous to an authenticated user.

The refresh method provides a mechanism to update your manually. It is manual polling.

Each request to the server will have an evaluation object as a response. Also, parameter is an evaluation object. You can retrieve the current evaluation object using method.

https://koople.io
NPM
evaluation object
evaluation object
evaluation object
evaluation object
bootRun
evaluation object
identify
evaluation object
evaluation object
evaluation object
evaluation object
evaluation object
fallback
evaluation
evaluation object
storage
evaluation object
bootRun
fallback
evaluation object
timeout
pollingInterval
evaluation object
evaluation object
evaluation object
evaluation object
User object