JavaScript SDK Reference
This topic explains how to use the Harness Feature Flags SDK in your JavaScript application. To learn more about using Feature Flags SDK with JavaScript application, clone and run a sample application from the JavaScript SDK GitHub repository.
In this topic:
- Before You Begin
- Prerequisites
- Use Harness Feature Flags SDKs with JavaScript Applications
- Sample Code for JavaScript Application
Before You Begin
- Feature Flags Overview
- Getting Started with Feature Flags
- Client-Side and Server-Side SDKs
- Communication Strategy Between SDKs and Harness Feature Flags
Prerequisites
- Create a feature flag in Harness Feature Flags. Feature flags wrap your code and allow you to manage the feature release in a controlled way. See Create a Feature Flag.
- Ensure that you have created your SDK Key. See Create an SDK Key.
- Download the Harness Feature Flag JavaScript Client SDK.
- A JavaScript application to test your feature flag. If you do not have your JavaScript Application, you can download a sample application from the JavaScript SDK GitHub repository.
- On the JavaScript Client SDK GitHub page, click Code and then clone the sample application. For more information, see Cloning a repository.
- Import your project in an IDE such as IntelliJ or Eclipse.
Use Harness Feature Flags SDKs with JavaScript Applications
Perform the following steps to get started with using the Feature Flags SDK in your JavaScript application:
Step 1: Install the JavaScript Feature Flag Client SDK
To install the Harness Feature Flag JavaScript client SDK in your application, simply run the following npm
or yarn
command:
npm i @harnessio/ff-javascript-client-sdk
or
yarn add @harnessio/ff-javascript-client-sdk
Step 2: Import the Feature Flag Client SDK
Import the client using the following command:
import { initialize, Event } from '@harnessio/ff-javascript-client-sdk'
Import Using unpkg
Refer to the Harness Feature Flag JavaScript SDK to identify the latest version for your build automation tool.
If you wish to import the library directly without having to use npm
or yarn
, run the following command:
<script type="module">
import { initialize, Event } from 'https://unpkg.com/@harnessio/[email protected]/dist/sdk.client.js'
</script>
If your browser does not support the ES modules, then run the following command:
<script src="https://unpkg.com/@harnessio/[email protected]/dist/sdk.client.js"></script>
<script>
var initialize = HarnessFFSDK.initialize
var Event = HarnessFFSDK.Event
</script>
Ensure that you verify the version in the unpkg
URL.
Step 3: Initialize the SDK
Now that the SDK is imported, you can configure and initialize it. You should enter your SDK keys when configuring the SDK so that your application is authorized to connect to Harness Feature Flags and retrieve flags for your environment.
initialize(FeatureFlagSDKKey: string, target: Target, options?: Options)
In which Target
and Options
are defined as:
interface Target {
identifier: string
name?: string
anonymous?: boolean
attributes?: object
}
interface Options {
baseUrl?: string
debug?: boolean
}
For example:
const cf = initialize('00000000-1111-2222-3333-444444444444', {
identifier: YOUR-TARGET-IDENTIFIER, // Target identifier
name: YOUR-TARGET-NAME, // Optional target name
attributes: { // Optional target attributes
email: '[email protected]'
}
});
Step 4: Listen to the cf
Instance Events
This method provides a way to listen to the different events that might be triggered by SDK, indicating a specific change in the SDK.
cf.on(Event.READY, flags => {
// Event happens when connection to server is established
// flags contains all evaluations against SDK key
})
cf.on(Event.CHANGED, flagInfo => {
// Event happens when a changed event is pushed
// flagInfo contains information about the updated feature flag
})
cf.on(Event.DISCONNECTED, () => {
// Event happens when connection is disconnected
})
cf.on(Event.ERROR, () => {
// Event happens when some connection error has occurred
})
Step 5: Evaluate Target for Your Feature Flag
Once you have initialized the Feature Flag client for a target, evaluate it for your feature flag. A feature flag is evaluated for a particular target.
const value = cf.variation('Dark_Theme', false) // second argument is default value when variation does not exist
Step 6: Remove Listeners
Remove a listener of an event using cf.off
.
cf.off(Event.ERROR, () => {
// Do something when an error occurs
})
Remove all listeners.
cf.off()
On closing your application, call cf.close()
to close the event stream.
cf.close();
Step 7: Verify Your Feature Flag
Run the application from your IDE and verify whether the flag variation value displayed on your application page is consistent with the feature flag you created.
Toggle the flag on and off to verify if your application is getting updated.
Sample Code for JavaScript Application
Here is a sample code for using Harness Feature Flag SDKs with a JavaScript application. To learn more about using the sample JavaScript application, see the JavaScript SDK GitHub repository.
var initialize = HarnessFFSDK.initialize
var Event = HarnessFFSDK.Event
var log = msg => {
document.querySelector('#log').innerHTML += `${msg}\n`
}
var cf = initialize(
'ed56f3ec-1aa6-4bc2-a519-6ebcc3f0541f',
{
identifier: 'Harness1',
attributes: {
lastUpdated: Date(),
host: location.href
}
}
)
cf.on(Event.READY, flags => {
log(JSON.stringify(flags, null, 2))
})
cf.on(Event.CHANGED, flagInfo => {
if (flagInfo.deleted) {
log('Flag is deleted')
log(JSON.stringify(flagInfo, null, 2))
} else {
log('Flag is changed')
log(JSON.stringify(flagInfo, null, 2))
}
})