> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/feature-management-experimentation/new-to-fme/sdks-and-customer-deployed-components/client-side-sdks/client-side-standard-sdks/javascript-sdk.md).
# JavaScript SDK
This guide provides detailed information about our JavaScript SDK. All of our SDKs are open source. Go to our [JavaScript SDK GitHub repository](https://github.com/splitio/javascript-client) to see the source code.
{% hint style="info" %}
**MIGRATING FROM V10.X TO V11.X**
When upgrading, consider that the traffic type is no longer configured for the SDK factory client, and must be sent on the `client.track()` method call instead.
Refer to the [migration guide](https://github.com/splitio/javascript-client/blob/development/MIGRATION-GUIDE.md) for complete information on upgrading to v11.x.
{% endhint %}
### Before you begin
The JavaScript SDK supports all major browsers. While the library was built to support ES5 syntax, it depends on native support for ES6 `Promise`, `Map`, and `Set` objects, and therefore, you need to **polyfill** them if they are not available in your target browsers.
If you're looking for possible polyfill options, check [es6-promise](https://github.com/stefanpenner/es6-promise), [es6-map](https://github.com/medikoo/es6-map) and [es6-set](https://github.com/medikoo/es6-set) for Promise, Map and Set polyfills respectively.
{% hint style="info" %}
**RULE-BASED SEGMENTS SUPPORT**
Rule-based segments are supported in SDK versions 11.4.0 and above. No changes are required to your SDK implementation, but updating to a supported version is required to ensure compatibility.
Older SDK versions will return the control treatment for flags using rule-based segments and log an impression with a special label for unsupported targeting rules.
{% endhint %}
### Initialization
Set up FME in your code base with two simple steps.
#### 1. Import the SDK into your project
You can import the SDK into your project using either of the three methods below.
{% tabs %}
{% tab title="NPM (recommended)" %}
```bash
npm install --save @splitsoftware/splitio
```
{% endtab %}
{% tab title="CDN bundle" %}
```html
```
{% endtab %}
{% endtabs %}
#### 2. Instantiate the SDK and create a new SDK factory client
{% tabs %}
{% tab title="JavaScript (using CDN)" %}
```javascript
// Instantiate the SDK. CDN will expose splitio globally
var factory = splitio({
core: {
authorizationKey: 'YOUR_SDK_KEY',
// key represents your internal user id, or the account id that
// the user belongs to.
// This could also be a cookie you generate for anonymous users
key: 'key'
}
});
// And get the client instance you'll use
var client = factory.client();
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
var SplitFactory = require('@splitsoftware/splitio').SplitFactory;
// Instantiate the SDK
var factory = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
// key represents your internal user id, or the account id that
// the user belongs to.
// This could also be a cookie you generate for anonymous users
key: 'key'
}
});
// And get the client instance you'll use
var client = factory.client();
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
// Use the import let = require syntax on TS.
import { SplitFactory } from '@splitsoftware/splitio';
// Instantiate the SDK
const factory: SplitIO.IBrowserSDK = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'key'
},
startup: {
readyTimeout: 1.5 // 1.5 sec
}
});
// And get the client instance you'll use
const client: SplitIO.IBrowserClient = factory.client();
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
**UPDATING TO V10 FOR NPM VERSION**
If you are using the CDN package or Bower, no changes are needed on your current code. We changed our module system to ES modules and now we are exposing an object with a `SplitFactory` property. That property points to the same factory function that we were returning in the previous versions. Refer to the snippet above to see the code.
{% endhint %}
{% hint style="info" %}
**NOTICE FOR TYPESCRIPT**
With the SDK package on NPM, you get the SplitIO namespace, which contains useful types and interfaces for you to use.
Feel free to dive into the declaration files if IntelliSense is not enough.
{% endhint %}
Harness recommends instantiating the SDK factory once as a singleton and reusing it throughout your application.
Configure the SDK with the SDK key for the FME environment that you would like to access. In legacy Split (app.split.io) the SDK key is found on your Admin settings page, in the API keys section. Select a client-side SDK API key. This is a special type of API token with limited privileges for use in browsers or mobile clients. See [API keys](/feature-management-experimentation/management-and-administration/api-keys.md) to learn more.
### Use the SDK
#### Basic use
When the SDK is instantiated, it starts background tasks to update an in-memory cache with small amounts of data fetched from Harness servers. This process can take up to a few hundred milliseconds, depending on the size of data. If the SDK is asked to evaluate which treatment to show to a customer for a specific feature flag while it's in this intermediate state, it may not have the data necessary to run the evaluation. In this case, the SDK does not fail, rather, it returns the [control treatment](/feature-management-experimentation/use-fme/feature-management/setup/control-treatment.md).
To make sure the SDK properly loads before asking it for a treatment, block until the SDK is ready, as shown below. We set the client to listen for the `SDK_READY` event triggered by the SDK before asking for an evaluation.
After the `SDK_READY` event fires, you can use the `getTreatment` method to return the proper treatment based on the feature flag name and the key you passed when instantiating the SDK. Then use an if-else-if block as shown below and insert the code for the different treatments that you defined in Harness FME. Remember the final else branch in your code to handle the client returning control.
{% tabs %}
{% tab title="JavaScript" %}
```javascript
client.on(client.Event.SDK_READY, function() {
var treatment = client.getTreatment('FEATURE_FLAG_NAME');
if (treatment == "on") {
// insert code here to show on treatment
} else if (treatment == "off") {
// insert code here to show off treatment
} else {
// insert your control treatment code here
}
});
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
client.on(client.Event.SDK_READY, function() {
const treatment: SplitIO.Treatment = client.getTreatment('FEATURE_FLAG_NAME');
if (treatment == "on") {
// insert code here to show on treatment
} else if (treatment == "off") {
// insert code here to show off treatment
} else {
// insert your control treatment code here
}
});
```
{% endtab %}
{% endtabs %}
#### Attribute syntax
To [target based on custom attributes](/feature-management-experimentation/use-fme/feature-management/targeting/target-with-custom-attributes.md), the SDK's `getTreatment` method needs to be passed an attribute map at runtime.
In the example below, we are rolling out a feature to users. The provided attributes `plan_type`, `registered_date`, `permissions`, `paying_customer`, and `deal_size` are passed to the `getTreatment` call. These attributes are compared and evaluated against the attributes used in the rollout plan as defined in Harness FME to decide whether to show the `on` or `off` treatment to this account.
The `getTreatment` method has a number of variations that are described below. Each of these additionally has a variation that takes an attributes argument, which can defines attributes of the following types: strings, numbers, dates, booleans, and sets. The proper data type and syntax for each are:
* **Strings:** Use type String.
* **Numbers:** Use type Number.
* **Dates:** Use type Date and express the value in `milliseconds since epoch`.\
**Note:** Milliseconds since epoch is expressed in UTC. If your date or date-time combination is in a different timezone, first convert it to UTC, then transform it to milliseconds since epoch.
* **Booleans:** Use type Boolean.
* **Sets:** Use type Array.
{% tabs %}
{% tab title="JavaScript" %}
```javascript
var attributes = {
// date attributes are handled as `millis since epoch`
registered_date: new Date('YYYY-MM-DDTHH:mm:ss.sssZ').getTime(),
// this string will be compared against a list called `plan_type`
plan_type: 'growth',
// this number will be compared against a const value called `deal_size`
deal_size: 10000,
// this boolean will be compared against a const value called `paying_customer`
paying_customer: true,
// this array will be compared against a set called `permissions`
permissions: ["read", "write"]
};
var treatment = client.getTreatment('FEATURE_FLAG_NAME', attributes);
if (treatment === 'on') {
// insert on code here
} else if (treatment === 'off') {
// insert off code here
} else {
// insert control code here
}
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
const attributes: SplitIO.Attributes = {
// date attributes are handled as `millis since epoch`
registered_date: new Date('YYYY-MM-DDTHH:mm:ss.sssZ').getTime(),
// this string will be compared against a list called `plan_type`
plan_type: 'growth',
// this number will be compared against a const value called `deal_size`
deal_size: 10000,
// this array will be compared against a set called `permissions`
permissions: [‘read’, ‘write’]
};
const treatment: SplitIO.Treatment = client.getTreatment('FEATURE_FLAG_NAME', attributes);
if (treatment === 'on') {
// insert on code here
} else if (treatment === 'off') {
// insert off code here
} else {
// insert control code here
}
```
{% endtab %}
{% endtabs %}
You can pass your attributes in exactly this way to the `client.getTreatments` method.
#### Binding attributes to the client
Attributes can optionally be bound to the client at any time during the SDK lifecycle. These attributes are stored in memory and used in every evaluation to avoid the need to keep the attribute set accessible through the whole app. When an evaluation is called, the attributes provided (if any) at evaluation time are combined with the ones that are already loaded into the SDK memory, with the ones provided at function execution time taking precedence. This enables those attributes to be overridden or hidden for specific evaluations.
An attribute is considered valid if it follows one of the types listed below:
* String
* Number
* Boolean
* Array
The SDK validates these before storing them and if there are invalid or missing values, possibly indicating an issue, the methods return the boolean `false` and do not update any value.
To use these methods, refer to the example below:
```javascript
var attributes = {
registered_date: new Date('YYYY-MM-DDTHH:mm:ss.sssZ').getTime(),
plan_type: 'growth',
deal_size: 10000,
paying_customer: true,
permissions: ["read", "write"]
};
// set attributes returns true unless there is an issue storing it
var result = client.setAttributes(attributes);
// set one attribute and returns true unless there is an issue storing it
var result = client.setAttribute('paying_customer', false);
// Get an attribute
var plan_type = client.getAttribute('plan_type');
// Get all attributes
var stored_attributes = client.getAttributes();
// Remove an attribute
var result = client.removeAttribute('permissions');
// Remove all attributes
var result = client.clearAttributes();
```
#### Multiple evaluations at once
In some instances, you may want to evaluate treatments for multiple feature flags at once. Use the different variations of `getTreatments` from the SDK factory client to do this.
* `getTreatments`: Pass a list of the feature flag names you want treatments for.
* `getTreatmentsByFlagSet`: Evaluate all flags that are part of the provided set name and are cached on the SDK instance.
* `getTreatmentsByFlagSets`: Evaluate all flags that are part of the provided set names and are cached on the SDK instance.
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// Getting treatments by feature flag names
var flagNames = ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2'];
var treatments = client.getTreatments(flagNames);
// Getting treatments by set
treatments = client.getTreatmentsByFlagSet('frontend');
// Getting treatments for the union of multiple sets
var flagSets = ['frontend', 'client_side'];
treatments = client.getTreatmentsByFlagSets(flagSets);
// treatments have the following form:
// {
// FEATURE_FLAG_NAME_1: 'on',
// FEATURE_FLAG_NAME_2: 'visa'
// }
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
// Getting treatments by feature flag names
const flagNames = ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2'];
let treatments: SplitIO.Treatments = client.getTreatments(flagNames);
// Getting treatments by set
treatments = client.getTreatmentsByFlagSet('frontend');
// Getting treatments for the union of multiple sets
const flagSets = ['frontend', 'client_side'];
treatments = client.getTreatmentsByFlagSets(flagSets);
// treatments have the following form:
// {
// FEATURE_FLAG_NAME_1: 'on',
// FEATURE_FLAG_NAME_2: 'visa'
// }
```
{% endtab %}
{% endtabs %}
#### Get treatments with configurations
To [leverage dynamic configurations with your treatments](/feature-management-experimentation/use-fme/feature-management/setup/dynamic-configurations.md), use the `getTreatmentWithConfig` method.
This method returns an object with the structure below:
```typescript
type TreatmentWithConfig = {
treatment: string;
config: string | null;
};
```
As you can see from the object structure, the config is a stringified version of the configuration JSON defined in Harness FME. If there is no configuration defined for a treatment, the SDK returns `null` for the config parameter.
This method takes the exact same set of arguments as the standard `getTreatment` method. Refer to the examples below for proper usage:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
var treatmentResult = client.getTreatmentWithConfig('FEATURE_FLAG_NAME', attributes);
var configs = JSON.parse(treatmentResult.config);
var treatment = treatmentResult.treatment;
if (treatment === 'on') {
// insert on code here and use configs here as necessary
} else if (treatment === 'off') {
// insert off code here and use configs here as necessary
} else {
// insert control code here
}
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
const treatmentResult: SplitIO.TreatmentWithConfig = client.getTreatmentWithConfig('FEATURE_FLAG_NAME', attributes);
const configs = JSON.parse(treatmentResult.config);
const treatment = treatmentResult.treatment;
if (treatment === 'on') {
// insert on code here and use configs here as necessary
} else if (treatment === 'off') {
// insert off code here and use configs here as necessary
} else {
// insert control code here
}
```
{% endtab %}
{% endtabs %}
If you need to get multiple evaluations at once, you can also use the `getTreatmentsWithConfig` methods. These methods take the exact same arguments as the [getTreatments](#multiple-evaluations-at-once) methods but return a mapping of feature flag names to TreatmentResults instead of strings. Example usage below:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// Getting treatments by feature flag names
var featureFlagNames = ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2'];
var treatmentResults = client.getTreatmentsWithConfig(featureFlagNames);
// Getting treatments by set
treatmentResults = client.getTreatmentsWithConfigByFlagSet('frontend');
// Getting treatments for the union of multiple sets
var flagSets = ['frontend', 'client_side'];
treatmentResults = client.getTreatmentsWithConfigByFlagSets(flagSets);
// treatmentResults will have the following form:
// {
// FEATURE_FLAG_NAME_1: {treatment: 'on',
// config: "{ 'color' : 'red'}}",
// FEATURE_FLAG_NAME_2: {treatment: 'v2',
// config: "{ 'copy' : 'better copy'}}",
// }
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
// Getting treatments by feature flag names
const featureFlagNames = ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2'];
let treatmentResults: SplitIO.TreatmentsWithConfig = client.getTreatmentsWithConfig(featureFlagNames);
// Getting treatments by set
treatmentResults = client.getTreatmentsWithConfigByFlagSet('frontend');
// Getting treatments for the union of multiple sets
const flagSets = ['frontend', 'client_side'];
treatmentResults = client.getTreatmentsWithConfigByFlagSets(flagSets);
// treatmentResults will have the following form:
// {
// FEATURE_FLAG_NAME_1: {treatment: 'on',
// config: "{ 'color' : 'red'}}",
// FEATURE_FLAG_NAME_2: {treatment: 'v2',
// config: "{ 'copy' : 'better copy'}}",
// }
```
{% endtab %}
{% endtabs %}
If a flag cannot be evaluated, the SDK returns the fallback treatment value (default `"control"` unless overridden globally or per flag). For more information, see [Fallback treatments](/feature-management-experimentation/use-fme/feature-management/setup/fallback-treatment.md).
#### Append properties to impressions
[Impressions](/feature-management-experimentation/use-fme/feature-management/monitoring-and-analysis/impressions.md) are generated by the SDK each time a `getTreatment` method is called. These impressions are periodically sent back to Harness servers for feature monitoring and experimentation.
You can append properties to an impression by passing an object of key-value pairs to the `getTreatment` method. These properties are then included in the impression sent by the SDK and can provide useful context to the impression data.
Three types of properties are supported: strings, numbers, and booleans.
{% tabs %}
{% tab title="JavaScript" %}
```javascript
const evaluationOptions = {
properties: {
package: "premium",
admin: true,
discount: 50
}
};
const treatment = client.getTreatment('FEATURE_FLAG_NAME', undefined, evaluationOptions);
```
{% endtab %}
{% tab title="TypeScript" %}
```typescript
const evaluationOptions: SplitIO.EvaluationOptions = {
properties: {
package: "premium",
admin: true,
discount: 50
}
};
const treatment: string = client.getTreatment('FEATURE_FLAG_NAME', undefined, evaluationOptions);
```
{% endtab %}
{% endtabs %}
#### Shutdown
Call the `client.destroy()` method before letting a process using the SDK exit, as this method gracefully shuts down the SDK by stopping all background threads, clearing caches, closing connections, and flushing the remaining unpublished impressions.
```javascript
// You can just destroy and remove the variable reference and move on:
user_client.destroy();
user_client = null;
// destroy() returns a promise, so if you want to, for example,
// navigate to another page without losing impressions, you
// can do that once the promise resolves.
user_client.destroy().then(function() {
user_client = null;
document.location.replace('another_page');
});
```
After `destroy()` is called and finishes, any subsequent invocations to `getTreatment`/`getTreatments` or manager methods result in `control` or empty list, respectively.
{% hint style="warning" %}
**IMPORTANT!**
A call to the `destroy()` method also destroys the factory object. When creating new client instance, first create a new factory instance.
{% endhint %}
### Track
Use the `track` method to record any actions your customers perform. Each action is known as an `event` and corresponds to an `event type`. Calling `track` through one of our SDKs or via the API is the first step to getting experimentation data into Harness FME and allows you to measure the impact of your features on your users’ actions and metrics.
Learn more about [tracking events](/feature-management-experimentation/use-fme/release-monitoring/events/index.md).
In the examples below you can see that the `.track()` method can take up to four arguments. The proper data type and syntax for each are:
* **TRAFFIC\_TYPE:** The traffic type of the key in the track call. The expected data type is **String**. You can only pass values that match the names of [traffic types](/feature-management-experimentation/management-and-administration/traffic-types.md) that you have defined Harness FME.
* **EVENT\_TYPE:** The event type that this event should correspond to. The expected data type is **String**. Full requirements on this argument are:
* Contains 63 characters or fewer.
* Starts with a letter or number.
* Contains only letters, numbers, hyphen, underscore, or period.
* This is the regular expression we use to validate the value: `[a-zA-Z0-9][-_\.a-zA-Z0-9]{0,62}`
* **VALUE:** (Optional) The value to be used in creating the metric. This field can be sent in as null or 0 if you intend to purely use the count function when creating a metric. The expected data type is **Integer** or **Float**.
* **PROPERTIES:** (Optional) An object of key value pairs that can be used to filter your metrics. Learn more about event property capture in the [Events](/feature-management-experimentation/use-fme/release-monitoring/events/index.md#event-properties) guide. FME currently supports three types of properties: strings, numbers, and booleans.
The `track` method returns a boolean value of `true` or `false` to indicate whether or not the SDK was able to successfully queue the event to be sent back to Harness servers on the next event post. The SDK will return `false` if the current queue size is equal to the config set by `eventsQueueSize` or if an incorrect input to the `track` method has been provided.
In the case that a bad input has been provided, you can read more about our SDK's expected behavior [here](/feature-management-experimentation/use-fme/release-monitoring/events/index.md).
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// Example with both a value and properties
var properties = { package: "premium", admin: true, discount: 50 };
var queued = client.track('user', 'page_load_time', 83.334, properties);
// Example with only properties
var properties = { package: "premium", admin: true, discount: 50 };
var queued = client.track('user', 'page_load_time', null, properties);
```
{% endtab %}
{% tab title="TypeScript" %}
```typescript
// Example with both a value and properties
const properties: SplitIO.Properties = { package: "premium", admin: true, discount: 50 };
const queued: boolean = client.track('user', 'page_load_time', 83.334, properties);
// Example with only properties
const properties = { package: "premium", admin: true, discount: 50 };
const queued = client.track('user', 'page_load_time', null, properties);
```
{% endtab %}
{% endtabs %}
### Configuration
The SDK has a number of knobs for configuring performance. Each knob is tuned to a reasonable default. However, you can override the value while instantiating the SDK. The parameters available for configuration are shown below.
| **Configuration** | **Description** | **Default value** |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| core.labelsEnabled | Enable impression labels from being sent to Harness servers. Labels may contain sensitive information. | true |
| startup.readyTimeout | Maximum amount of time in seconds to wait before firing the `SDK_READY_TIMED_OUT` event | 10 |
| startup.requestTimeoutBeforeReady | The SDK has two main endpoints it uses /splitChanges and /memberships that it hits to get ready. This config sets how long (in seconds) the SDK waits for each request it makes as part of getting ready. | 5 |
| startup.retriesOnFailureBeforeReady | How many retries on /splitChanges and /memberships we do while getting the SDK ready | 1 |
| startup.eventsFirstPushWindow | Use to set a specific timer (expressed in seconds) for the first push of events, starting on SDK initialization. | 10 |
| scheduler.featuresRefreshRate | The SDK polls Harness servers for changes to feature rollout plans. This parameter controls this polling period in seconds. | 60 |
| scheduler.segmentsRefreshRate | The SDK polls Harness servers for changes to segment definitions. This parameter controls this polling period in seconds. | 60 |
| scheduler.impressionsRefreshRate | The SDK sends information on who got what treatment at what time back to Harness servers to power analytics. This parameter controls how often this data is sent to Harness servers. The parameter should be in seconds. | 300 |
| scheduler.impressionsQueueSize | The max amount of impressions we queue. If the queue is full, the SDK flushes the impressions and resets the timer. | 30000 |
| scheduler.eventsPushRate | The SDK sends tracked events to Harness servers. This setting controls that flushing rate in seconds. | 60 |
| scheduler.eventsQueueSize | The max amount of events we queue. If the queue is full, the SDK flushes the events and resets the timer. | 500 |
| scheduler.telemetryRefreshRate | The SDK caches diagnostic data that it periodically sends to Harness servers. This configuration controls how frequently this data is sent back to Harness servers (in seconds). | 3600 seconds (1 hour) |
| sync.splitFilters | Filter specific feature flags to be synced and evaluated by the SDK. This is formed by a type string property and a list of string values for the given criteria. Using the types 'bySet' (recommended, flag sets are available in all tiers) or 'byName', pass an array of strings defining the query. If empty or unset, all feature flags are downloaded by the SDK. | \[] |
| sync.impressionsMode | This configuration defines how impressions (decisioning events) are queued on the SDK. Supported modes are OPTIMIZED, NONE, and DEBUG. In OPTIMIZED mode, only unique impressions are queued and posted to Harness; this is the recommended mode for experimentation use cases. In NONE mode, no impression is tracked in Harness FME and only minimum viable data to support usage stats is, so never use this mode if you are experimenting with that instance impressions. Use NONE when you want to optimize for feature flagging only use cases and reduce impressions network and storage load. In DEBUG mode, ALL impressions are queued and sent to Harness; this is useful for validations. This mode doesn't impact the impression listener which receives all generated impressions locally. | `OPTIMIZED` |
| sync.enabled | Controls the SDK continuous synchronization flags. When `true`, a running SDK processes rollout plan updates performed in Harness FME (default). When `false`, it fetches all data from the Harness FME servers only upon init, which ensures a consistent experience during a user session and optimizes resources when these updates are not consumed by the app. | true |
| sync.requestOptions.getHeaderOverrides | A callback function that can be used to override the Authentication header or append new headers to the SDK's HTTP(S) requests. | undefined |
| storage.type | Storage type to be used by the SDK. Possible values are `MEMORY` and `LOCALSTORAGE`. | `MEMORY` |
| storage.prefix | Only applies to the `LOCALSTORAGE` storage type. An optional prefix for your data to avoid collisions. This prefix is prepended to the existing "SPLITIO" localStorage prefix. | `SPLITIO` |
| storage.expirationDays | Only applies to the `LOCALSTORAGE` storage type. Number of days before cached data expires if it was not updated. If cache expires, it is cleared when the SDK is initialized. | 10 |
| storage.clearOnInit | Only applies to the `LOCALSTORAGE` storage type. When set to `true`, the SDK clears the cached data on initialization unless it was cleared within the last 24 hours. This 24-hour window is not configurable. If the cache is cleared (whether due to expiration or `clearOnInit`), both the 24-hour period and the `expirationDays` period are reset. | false |
| storage.wrapper | Only applies to the `LOCALSTORAGE` storage type. Storage wrapper used to persist the SDK cached data. | `localStorage` |
| debug | Either a boolean flag or log level string ('ERROR', 'WARN', 'INFO', or 'DEBUG'). See [logging](#logging) for details. | false |
| streamingEnabled | Boolean flag to enable the streaming service as default synchronization mechanism. In the event of an issue with streaming, the SDK falls back to the polling mechanism. If false, the SDK polls for changes as usual without attempting to use streaming. | true |
| userConsent | User consent status used to control the tracking of events and impressions. Possible values are `GRANTED`, `DECLINED`, and `UNKNOWN`. See [User consent](#user-consent) for details. | `GRANTED` |
| fallbackTreatments | Configure fallback treatments for the SDK. | undefined |
To set each of the parameters defined above, use the following syntax:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
var sdk = SplitFactory({
startup: {
requestTimeoutBeforeReady: 5, // 5 sec
retriesOnFailureBeforeReady: 1, // 1 sec
readyTimeout: 10, // 10 sec
eventsFirstPushWindow: 10 // 10 sec
},
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'USER_ID'
},
scheduler: {
featuresRefreshRate: 5, // 5 sec
segmentsRefreshRate: 60, // 60 sec
impressionsRefreshRate: 300, // 300 sec
impressionsQueueSize: 30000, // 30000 items
eventsPushRate: 60, // 60 sec
eventsQueueSize: 500, // 500 items
telemetryRefreshRate: 3600 // 1 hour
},
sync: {
splitFilters: [{
type: 'bySet',
values: ['frontend']
}],
impressionsMode: 'NONE'
},
storage: {
type: 'LOCALSTORAGE',
prefix: 'MYPREFIX',
expirationDays: 10,
clearOnInit: false,
wrapper: window.localStorage
},
streamingEnabled: true,
debug: false
});
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
const sdk: SplitIO.IBrowserSDK = SplitFactory({
startup: {
requestTimeoutBeforeReady: 5, // 5 sec
retriesOnFailureBeforeReady: 1, // 1 sec
readyTimeout: 10, // 10 sec
eventsFirstPushWindow: 10 // 10 sec
},
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'USER_ID'
},
scheduler: {
featuresRefreshRate: 5, // 5 sec
segmentsRefreshRate: 60, // 60 sec
impressionsRefreshRate: 300, // 300 sec
impressionsQueueSize: 30000, // 30000 items
eventsPushRate: 60, // 60 sec
eventsQueueSize: 500, // 500 items
telemetryRefreshRate: 3600 // 1 hour
},
sync: {
splitFilters: [{
type: 'bySet',
values: ['frontend']
}],
impressionsMode: 'NONE'
},
storage: {
type: 'LOCALSTORAGE',
prefix: 'MYPREFIX',
expirationDays: 10,
clearOnInit: false,
wrapper: window.localStorage
},
streamingEnabled: true,
debug: false
});
```
{% endtab %}
{% endtabs %}
### Localhost mode
For testing, a developer can put code behind feature flags on their development machine without the SDK requiring network connectivity. To achieve this, the SDK can be started in **localhost** mode (aka off-the-grid or offline mode). In this mode, the SDK neither polls nor updates Harness servers. Instead, it uses an in-memory data structure to determine what treatments to show to the logged in customer for each of the features.
When instantiating the SDK in localhost mode, your `authorizationKey` is `localhost`. Define the feature flags you want to use in the `features` object map. All `getTreatment` calls for a feature flag now only return the one treatment (and config, if defined) that you have defined in the map.
Any feature that is not provided in the `features` map returns the [control treatment](/feature-management-experimentation/use-fme/feature-management/setup/control-treatment.md) if the SDK was asked to evaluate them.
You can use the additional configuration parameters below when instantiating the SDK in `localhost` mode.
| **Configuration** | **Description** | **Default value** |
| ---------------------------- | ------------------------------------------------------------------- | --------------------------------------------------- |
| scheduler.offlineRefreshRate | The refresh interval for the mocked features treatments. | 15 |
| features | A fixed mapping of which treatment to show for our mocked features. | {}
By default we have no mocked features.
|
To use the SDK in localhost mode, replace the SDK key on `authorizationKey` property with `'localhost'`, as shown in the example below. Note that you can define in the `features` object a feature flag name and its treatment directly or use a map to define both a treatment and a dynamic configuration.
If you define just a string as the value for a feature flag name, any config returned by our SDKs are always null. If you use a map, we return the specified treatment and the specified config (which can also be null).
{% tabs %}
{% tab title="JavaScript (using CDN)" %}
```javascript
var sdk = splitio({
core: {
authorizationKey: 'localhost',
key: 'CUSTOMER_ID'
},
features: {
'reporting_v2': 'on', // example with just a string value for the treatment
'billing_updates': { treatment: 'visa', config: '{ "color": "blue" }' }, // example of a defined config
'show_status_bar': { treatment: 'off', config: null } // example of a null config
},
scheduler: {
offlineRefreshRate: 15 // 15 sec
}
});
var client = sdk.client();
// The following code will be evaluated once the engine finishes the initialization
client.on(client.Event.SDK_READY, function() {
// The sentence below will return 'on'
var t1 = client.getTreatment('reporting_v2')
// The sentence below will return an object with the structure of: {treatment:'visa',config:'{ "color":"blue" }'}
var t2 = client.getTreatmentWithConfig('billing_updates')
// The sentence below will return 'control' because that feature does not exist
var t3 = client.getTreatmentWithConfig('navigation_bar_changes')
});
// The following code will be evaluated only if using the LocalStorage option as storage type.
// The only difference with the production mode is that the event is always emitted in localhost mode,
// since the SDK can evaluate using the features provided by your `features` config object.
client.on(client.Event.SDK_READY_FROM_CACHE, function() {
// The sentence below will return 'on'
var t1 = client.getTreatment('reporting_v2')
}
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
const sdk: SplitIO.IBrowserSDK = SplitFactory({
core: {
authorizationKey: 'localhost',
key: 'CUSTOMER_ID'
},
features: {
'reporting_v2': 'on', // example with just a string value for the treatment
'billing_updates': { treatment: 'visa', config: '{ "color": "blue"}' } // example of a defined config
'show_status_bar': { treatment: 'off', config: null } // example of a null config
},
scheduler: {
offlineRefreshRate: 15 // 15 sec
}
});
const client: SplitIO.IBrowserClient = sdk.client();
// The following code will be evaluated once the engine finishes the initialization
client.on(client.Event.SDK_READY, () => {
// The sentence below will return 'on'
const t1: SplitIO.Treatment = client.getTreatment('reporting_v2');
// The sentence below will return an object with the structure of: {treatment:'visa',config:'{ "color":"blue" }'
const t2: SplitIO.Treatment = client.getTreatmentWithConfig('billing_updates');
// The sentence below will return 'control' because that feature does not exist
const t3: SplitIO.Treatment = client.getTreatmentWithConfig('navigation_bar_changes');
});
// The following code will be evaluated only if using the LocalStorage option as storage type.
// The only difference with the production mode is that the event is always emitted in localhost mode,
// since the SDK can evaluate using the features provided by your `features` config object.
client.on(client.Event.SDK_READY_FROM_CACHE, () => {
// The sentence below will return 'on'
const t1: SplitIO.Treatment = client.getTreatment('reporting_v2')
}
```
{% endtab %}
{% endtabs %}
You can then change the feature flags as necessary for your testing, by mutating the properties of the `features` object you've provided. The SDK simulates polling for changes every `offlineRefreshRate` seconds, and will emit an `SDK_UPDATE` event if the mocked features have changed.
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// The SDK keeps a reference to the `features` object map, so you can mutate the object as follows to emit SDK_UPDATE events:
config.features['reporting_v2'] = 'off'; // update reporting_v2
config.features['reporting_v3'] = 'off'; // add reporting_v3
delete config.features['reporting_v2']; // delete reporting_v2
// In case you need to update the whole mock object, you can replace the internal reference from the factory:
factory.settings.features = { 'reporting_v3': 'off' };
// But don't do it on the passed configuration, as the SDK will not reference the new object:
config.features = { 'reporting_v3': 'off' }; // Will not emit SDK_UPDATE
```
{% endtab %}
{% endtabs %}
#### Localhost mode limitations and Allowlist workaround
JavaScript, React, Redux, and Browser SDKs use the `features` configuration parameter to set feature flags and treatment names when running in localhost mode. However, this mode does not support adding Allowlist keys within the `features` property, unlike the YAML file structure used in server-side SDKs.
To mimic the behavior of allowing specific keys to receive certain treatments, you can define multiple feature flag sets keyed by your user identifier and select the appropriate set dynamically. This approach lets you flip treatments based on the key, effectively simulating an Allowlist.
For example:
```javascript
const myFeatures = {
agus: {
flag1: 'on',
flag2: 'off'
},
sanjay: {
flag1: 'off',
flag2: 'on'
},
default: {
flag1: 'off',
flag2: 'off'
}
};
const config = {
core: {
authorizationKey: 'localhost',
key: myKey
},
features: myFeatures[myKey] || myFeatures['default'],
startup: {
readyTimeout: 5, // 5 seconds
retriesOnFailureBeforeReady: 3 // 3 retries
}
};
```
This approach provides a simple way to control feature flag treatments per user key while running your application locally.
### Manager
Use the Split manager to get a list of features available to the SDK factory client. To instantiate a Manager in your code base, use the same factory that you used for your client.
{% tabs %}
{% tab title="JavaScript" %}
```javascript
var factory = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'key'
}
});
var manager = factory.manager();
manager.once(manager.Event.SDK_READY, function() {
// Once it's ready, use the manager
});
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
const factory: SplitIO.IBrowserSDK = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'key'
}
});
const manager: SplitIO.IManager = factory.manager();
manager.once(manager.Event.SDK_READY, function() {
// Once it's ready, use the manager
});
```
{% endtab %}
{% endtabs %}
The Manager then has the following methods available:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
/**
* Returns the feature flag registered within the SDK that matches this name.
*
* @return SplitView or null.
*/
var splitView = manager.split('name-of-feature-flag');
/**
* Retrieves all the feature flags that are currently registered within the SDK.
*
* returns a List of SplitViews.
*/
var splitViewsList = manager.splits();
/**
* Returns the names of all features flags registered within the SDK.
*
* @return a List of Strings of the features' names.
*/
var splitNamesList = manager.names();
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
/**
* Returns the feature flag registered within the SDK that matches this name.
*
* @return SplitView or null.
*/
const splitView: SplitIO.SplitView = manager.split('name-of-feature-flag');
/**
* Retrieves all the feature flags that are currently registered within the SDK.
*
* returns a List of SplitViews.
*/
const splitViewsList: SplitIO.SplitViews = manager.splits();
/**
* Returns the names of all features flags registered within the SDK.
*
* @return a List of Strings of the features' names.
*/
const splitNamesList: SplitIO.SplitNames = manager.names();
```
{% endtab %}
{% endtabs %}
The `SplitView` object referenced above has the following structure:
```typescript
type SplitView = {
name: string,
trafficType: string,
killed: boolean,
treatments: Array,
changeNumber: number,
configs: {
[treatmentName: string]: string
},
defaultTreatment: string,
sets: Array,
impressionsDisabled: boolean
}
```
### Listener
FME SDKs send impression data back to Harness servers periodically and as a result of evaluating feature flags. To additionally send this information to a location of your choice, define and attach an *impression listener*. For that purpose, the SDK's configurations have a parameter called `impressionListener` where an implementation of `ImpressionListener` could be added. This implementation **must** define the `logImpression` method and it receives data in the following schema.
| **Name** | **Type** | **Description** |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------- |
| impression | Object | Impression object that has the feature, key, treatment, label, etc. |
| attributes | Object | A map of attributes passed to `getTreatment`/`getTreatments` (if any). |
| sdkLanguageVersion | String | The version of the SDK. In this case the language is `javascript` plus the version currently running. |
{% hint style="info" %}
**NOTE**
There are two additional keys on this object, `ip` and `hostname`. They are not used on the browser.
{% endhint %}
### Implement custom impression listener
The following is an example of how to implement a custom impression listener:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
function logImpression(impressionData) {
// do something with the impression data.
}
var factory = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'key'
},
impressionListener: {
logImpression: logImpression
}
});
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
class MyImprListener implements SplitIO.IImpressionListener {
logImpression(impressionData: SplitIO.ImpressionData) {
// do something with impressionData
}
}
const factory: SplitIO.IBrowserSDK = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'key'
},
impressionListener: {
logImpression: new MyImprListener()
}
});
```
{% endtab %}
{% endtabs %}
An impression listener is called asynchronously from the corresponding evaluation, but is almost immediate.
Even though the SDK does not fail, if there is an exception in the listener, do not block the call stack.
### Content Security Policy (CSP)
The Content Security Policy (CSP) can be enabled on a site that uses the JavaScript SDK. CSP is a security standard to prevent cross-site scripting (XSS) and other code injection attacks.
To allow the JavaScript SDK, you can use the `nonce` keyword to permit inline scripts securely:
1. Configure your server to send a response header like this (with your own random nonce value): `Content-Security-Policy: script-src 'self' cdn.split.io 'nonce-swfT4W3546RtDw4';`.
2. Add the matching nonce attribute to the script tag that uses the SDK:
```html
```
Make sure the nonce value in the header and script tag match exactly. The nonce should be randomly generated per request for security.
### Logging
To enable SDK logging in the browser, open your DevTools console and type the following:
```javascript
// Acceptable values are 'DEBUG', 'INFO', 'WARN', 'ERROR' and 'NONE'
// Other acceptable values are 'on', 'enable' and 'enabled', which are equivalent to 'DEBUG' log level
localStorage.splitio_debug = 'on'
```
Reload the browser to start seeing the logs.
Beginning with v9.2.0 of the SDK, you can also enable the logging via SDK settings and programmatically by calling the Logger API.
{% tabs %}
{% tab title="Logger API" %}
```javascript
import { SplitFactory } from '@splitsoftware/splitio';
const sdk = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'key'
},
debug: true // Debug boolean option can be passed on settings.
// It takes precedence over the localStorage flag.
});
// Or you can use the Logger API which two methods, enable and disable.
// Calling this methods will have an immediate effect.
sdk.Logger.enable();
sdk.Logger.disable();
// You can also set the log level programmatically after v10.4.0
// Acceptable values are: 'DEBUG', 'INFO', 'WARN', 'ERROR', 'NONE'.
// 'DEBUG' is equivalent to `enable` method.
// 'NONE' is equivalent to `disable` method.
sdk.Logger.setLogLevel('WARN');
```
{% endtab %}
{% endtabs %}
By default, the SDK uses the `console.log` method to output log messages for all log levels.
Since v11.7.0 of the SDK, you can provide a custom logger to handle SDK log messages by setting the `logger` configuration option or using the `factory.Logger.setLogger` method.
The logger object must implement the `SplitIO.Logger` interface, which is compatible with the `console` object and logging libraries such as `winston`, `pino`, and `log4js`. The interface is defined as follows:
```typescript
interface Logger {
debug(message: string): any;
info(message: string): any;
warn(message: string): any;
error(message: string): any;
}
```
The following example passes the `console` object as a logger, so that `console.error`, `console.warn`, `console.info`, and `console.debug` methods are called rather than the default `console.log` method.
{% tabs %}
{% tab title="Using Console as Logger" %}
```typescript
import { SplitFactory } from '@splitsoftware/splitio';
const sdk = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'key'
},
// Enable logs to call the corresponding custom logger methods
debug: true,
logger: console
});
```
{% endtab %}
{% endtabs %}
### Configure fallback treatments
Fallback treatments let you define a treatment value (and optional configuration) to be returned when a flag cannot be evaluated. By default, the SDK returns `control`, but you can override this globally or for individual flags at the SDK level.
This is useful when you want to:
* Maintain a predictable user experience during outages or evaluation failures (avoid unexpected `control` in production)
* Protect critical user flows by returning a safe, stable treatment (for example, forcing `off` during an incident)
* Customize behavior per flag so each evaluation inherits appropriate safe defaults if something goes wrong
#### Global fallback treatment
Set a global fallback treatment when initializing the SDK factory. This value is returned whenever any flag cannot be evaluated.
```javascript
// Initialize SDK with global fallback treatment
const factory = SplitFactory({
core: {
authorizationKey: 'YOUR_CLIENT_SIDE_SDK_KEY',
key: 'USER_ID'
},
fallbackTreatments: {
global: {
treatment: 'global-treatment',
config: '{"global": true}'
},
}
});
const client = factory.client();
```
#### Flag-level fallback treatment
You can also set a fallback treatment per flag when calling `getTreatment` or `getTreatmentWithConfig`. This flag-level fallback always takes precedence over the global fallback treatment, so if both are defined, the SDK will return the flag-level value when that flag cannot be evaluated.
```javascript
// Initialize SDK with a per-flag fallback treatment
const factory = SplitFactory({
core: {
authorizationKey: 'YOUR_CLIENT_SIDE_SDK_KEY',
key: 'USER_ID'
},
fallbackTreatments: {
byFlag: {
'my_feature': {
treatment: 'flag-level-treatment',
config: '{"global": false}'
},
'my_other_feature': 'off'
}
}
});
const client = factory.client();
```
For more information, see [Fallback treatments](/feature-management-experimentation/use-fme/feature-management/setup/fallback-treatment.md).
### Advanced use cases
This section describes advanced use cases and features provided by the SDK.
#### Instantiate multiple SDK clients
Each JavaScript SDK factory client is tied to one specific customer and traffic type at a time (for example, `user`, `account`, `organization`). This enhances performance and reduces data cached within the SDK.
FME supports the ability to release based on multiple traffic types. With traffic types, you can release to `users` in one feature flag and `accounts` in another. If you are unfamiliar with using multiple traffic types, refer to [Traffic types](/feature-management-experimentation/management-and-administration/traffic-types.md) for more information.
If you need to roll out features by different traffic types, instantiate multiple SDK clients, one for each traffic type. For example, you may want to roll out the feature `user-poll` by `users` and the feature `account-permissioning` by `accounts`. You can do this with the example below:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
var factory = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'CUSTOMER_ACCOUNT_ID',
// Instantiate the sdk once and provide the ID for one of the
// traffic types that you plan to release to. It doesn't
// matter which you pick to start off with.
},
});
// now when you call factory.client(), the sdk will create a client
// using the Account ID you passed in during the factory creation.
var account_client = factory.client();
// to create another client for a User traffic type instead,
// just pass in a User ID to the factory.client() method.
// This is only valid after at least one client has been initialized.
var user_client = factory.client('CUSTOMER_USER_ID');
// check treatment for user-poll and CUSTOMER_USER_ID
var user_poll_treatment = user_client.getTreatment('user-poll');
// check treatment for account-permissioning and CUSTOMER_ACCOUNT_ID
var account_permissioning_treatment = account_client.getTreatment('account-permissioning');
// track events for user traffic type
user_client.track('user', 'PAGELOAD', 7.86);
// or track events for account traffic type
account_client.track('account', 'ACCOUNT_CREATED');
```
{% endtab %}
{% tab title="TypeScript" %}
```javascript
const sdk: SplitIO.IBrowserSDK = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'CUSTOMER_ACCOUNT_ID'
// instantiate the sdk once and provide the ID for one of the
// traffic types that you plan to release to. It doesn't
// matter which you pick to start off with.
},
});
// now when you call sdk.client(), the sdk will create a client
// using the Account ID you passed in during the factory creation.
const account_client: SplitIO.IBrowserClient = factory.client();
// to create another client for a User instead, just pass in a
// User ID to the sdk.client() method. This is only valid after
// at least one client has been initialized.
const user_client: SplitIO.IBrowserClient =
factory.client('CUSTOMER_USER_ID');
// check treatment for user-poll and CUSTOMER_USER_ID
const user_poll_treatment: SplitIO.Treatment =
user_client.getTreatment('user-poll');
// check treatment for account-permissioning and CUSTOMER_ACCOUNT_ID
const account_permissioning_treatment: SplitIO.Treatment =
account_client.getTreatment('account-permissioning');
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**NUMBER OF SDK INSTANCES**
While the SDK does not put any limitations on the number of instances that can be created, we strongly recommend keeping the number of SDKs down to **one** or **two**.
{% endhint %}
#### Subscribe to events
You can listen for four different events from the SDK.
* `SDK_READY_FROM_CACHE`. This event fires when the SDK is ready to evaluate treatments. If the SDK is using the `LOCALSTORAGE` storage type, it will attempt to use a locally cached version of your rollout plan from a previous session. By default, the `localStorage` API is used to cache the rollout plan (see [Configuration](#configuration) for more information). If data is cached, this event fires almost immediately, since access to the cache is fast, but data might be stale. Otherwise, it fires together with the `SDK_READY` event when the SDK downloads the rollout plan from Harness servers.
* `SDK_READY`. This event fires once the SDK is ready to evaluate treatments using the most up-to-date version of your rollout plan, downloaded from Harness servers.
* `SDK_READY_TIMED_OUT`. This event fires if the SDK could not download the data from Harness servers (`SDK_READY` event), within the time specified by the `startup.readyTimeout` configuration parameter. This event does not indicate that the SDK initialization was interrupted. The SDK continues downloading the rollout plan and fires the `SDK_READY` event when finished. This delayed `SDK_READY` event may happen with slow connections or large rollout plans with many feature flags, segments, or dynamic configurations.
* `SDK_UPDATE`. This event fires whenever your rollout plan is changed. Listen for this event to refresh your app whenever a feature flag or segment is changed in Harness FME.
The syntax to listen for each event is shown below:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
function whenReady() {
const treatment = client.getTreatment('FEATURE_FLAG_NAME');
if (treatment === 'on') {
// insert on code
} else if (treatment === 'off') {
// insert off code
} else {
// insert control code (usually the same as default treatment)
}
}
client.once(client.Event.SDK_READY, () => {
// The client is ready to evaluate treatments with the latest feature flag definitions synchronized from the server
whenReady();
});
client.once(client.Event.SDK_READY_TIMED_OUT, () => {
// This callback will be called after `startup.readyTimeout` seconds (10 seconds by default)
// if and only if the client is not ready for that time.
// You can still call `getTreatment()` but it could return `CONTROL`.
});
client.on(client.Event.SDK_UPDATE, () => {
// Fired each time the client state changes.
// For example, when a feature flag or a segment changes.
});
client.once(client.Event.SDK_READY_FROM_CACHE, () => {
// The client is ready to evaluate treatments, but not necessarily with the latest feature flag definitions synchronized from the server.
// Fired after the SDK could confirm the presence of the FME data.
// This event can fire really quickly, if data is cached from a previous session.
// Keep in mind that data might be stale, this is NOT a replacement of SDK_READY.
});
```
{% endtab %}
{% endtabs %}
**Include metadata**
{% hint style="info" %}
**SUPPORTED SDK VERSIONS**
Event metadata is supported in the JavaScript SDK version 11.10.0 or later.
{% endhint %}
`metadata` provides additional context for events:
* `SDK_READY` / `SDK_READY_FROM_CACHE`: Includes `initialCacheLoad` (true if no cached data from a previous session was available) and `lastUpdateTimestamp` (milliseconds since epoch when the cache was last updated).
* `SDK_UPDATE`: Includes `type` (`FLAGS_UPDATE` or `SEGMENTS_UPDATE`) and `names` (list of impacted flags; empty for segment-only updates).
* `SDK_READY_TIMED_OUT`: No metadata is included.
For example:
```javascript
client.on(client.Event.SDK_UPDATE, (metadata: SplitIO.SdkUpdateMetadata) => {
const type: SplitIO.SdkUpdateMetadataType = metadata.type;
const names: string[] = metadata.names;
})
client.on(client.Event.SDK_READY, (metadata: SplitIO.SdkReadyMetadata) => {
const initialCacheLoad: boolean = metadata.initialCacheLoad;
const lastUpdateTimestamp: number | undefined = metadata.lastUpdateTimestamp;
})
client.on(client.Event.SDK_READY_FROM_CACHE, (metadata: SplitIO.SdkReadyMetadata) => {
const initialCacheLoad: boolean = metadata.initialCacheLoad;
const lastUpdateTimestamp: number | undefined = metadata.lastUpdateTimestamp;
})
client.on(client.Event.SDK_READY_TIMED_OUT, () => {
console.log('Split SDK emitted SDK_READY_TIMED_OUT event.')
})
```
**Using readiness state and promises**
The `SDK_READY_FROM_CACHE`, `SDK_READY`, and `SDK_READY_TIMED_OUT` events fire only once. Therefore, if an event listener is attached after the event has already fired, it will never be triggered.
For this reason, you can check the SDK readiness state using the `client.getStatus()` method to determine whether the SDK is ready to evaluate treatments, among other things:
```javascript
const {
isReady, // true if the SDK_READY event was emitted
isReadyFromCache, // true if the SDK_READY_FROM_CACHE event was emitted
hasTimedout, // true if the SDK_READY_TIMED_OUT event was emitted
lastUpdate // timestamp of the most recent event
} = client.getStatus();
if (isReady) {
whenReadyCallback();
} else {
client.on(client.Event.SDK_READY, whenReadyCallback);
}
```
As an alternative to event listeners, you can also use the client promise methods `whenReady` and `whenReadyFromCache` to wait for the SDK to become ready.
* The `whenReadyFromCache()` promise resolves once the `SDK_READY_FROM_CACHE` event is emitted, or rejects if the `SDK_READY_TIMED_OUT` event is emitted first.
* The `whenReady()` promise resolves when the `SDK_READY` event is emitted, or rejects if the `SDK_READY_TIMED_OUT` event is emitted first. Subsequent calls to `client.whenReady()` may return a new promise with a different settled state. For instance, a resolved promise if the SDK becomes ready after the `SDK_READY_TIMED_OUT` event was triggered first.
{% tabs %}
{% tab title="whenReadyFromCache()" %}
```javascript
client.whenReadyFromCache().then(() => {
// SDK_READY_FROM_CACHE event has been emitted
const treatment = client.getTreatment("FEATURE_FLAG_NAME");
console.log("Treatment = " + treatment);
}).catch((e) => {
// SDK_READY_TIMED_OUT event has been emitted
console.error("SDK_READY_TIMED_OUT event emitted");
});
```
{% endtab %}
{% tab title="whenReady()" %}
```javascript
client.whenReady().then(() => {
// SDK_READY event has been emitted
const treatment = client.getTreatment("FEATURE_FLAG_NAME");
console.log("Treatment = " + treatment);
}).catch((e) => {
// SDK_READY_TIMED_OUT event has been emitted
console.error("SDK_READY_TIMED_OUT event emitted");
});
```
{% endtab %}
{% endtabs %}
#### User consent
The SDK allows you to disable the tracking of events and impressions until user consent is explicitly granted or declined.
The `userConsent` configuration parameter lets you set the initial consent status of the SDK instance, and the factory method `UserConsent.setStatus(boolean)` lets you grant (enable) or decline (disable) dynamic data tracking.
There are three possible initial states:
* `'GRANTED'`: The user grants consent for tracking events and impressions. The SDK sends them to Harness FME servers. This is the default value if `userConsent` param is not defined.
* `'DECLINED'`: The user declines consent for tracking events and impressions. The SDK does not send them to Harness FME servers.
* `'UNKNOWN'`: The user neither grants nor declines consent for tracking events and impressions. The SDK tracks them in its internal storage, and eventually either sends them or not if the consent status is updated to `'GRANTED'` or `'DECLINED'` respectively.
The status can be updated at any time with the `UserConsent.setStatus` factory method.
Working with user consent is demonstrated below.
```javascript
var factory = SplitFactory({
core: {
authorizationKey: 'YOUR_SDK_KEY',
key: 'key'
},
// Overwrites the initial consent status of the factory instance, which is 'GRANTED' by default.
// 'UNKNOWN' status represents that the user has neither granted nor declined consent for tracking data,
// so the SDK will locally track data but not send it to Harness FME servers until consent is changed to 'GRANTED'.
userConsent: 'UNKNOWN'
});
// `getStatus` method returns the current consent status.
factory.UserConsent.getStatus() === factory.UserConsent.Status.UNKNOWN;
// `setStatus` method lets you update the factory consent status at any time.
// Pass `true` for 'GRANTED' and `false` for 'DECLINED'.
factory.UserConsent.setStatus(true); // Consent status changed from 'UNKNOWN' to 'GRANTED'. Data will be sent to Harness FME servers.
factory.UserConsent.getStatus() === factory.UserConsent.Status.GRANTED;
factory.UserConsent.setStatus(false); // Consent status changed from 'GRANTED' to 'DECLINED'. Data will not be sent to Harness FME servers.
factory.UserConsent.getStatus() === factory.UserConsent.Status.DECLINED;
```
### Example apps
The following example applications detail how to configure and instantiate the JavaScript SDK on commonly used platforms:
* [Basic HTML](https://github.com/splitio/example-javascript-client)
* [AngularJS](https://github.com/splitio/angularjs-sdk-examples)
### Troubleshooting
#### User IDs Being Double Bucketed (SDK\_READY\_TIMED\_OUT Event Issue)
Using the JavaScript SDK, some percentage of User IDs are double bucketed: the same User ID is processed in the Control block, and at a later call in an actual treatment block.
One possible root cause is that the JavaScript SDK engine completes fetching treatments after the `startup.requestTimeoutBeforeReady` or `startup.readyTimeout` parameter expires, firing the browser event `SDK_READY_TIMED_OUT`.
This tends to happen for mobile users with slow internet connections.
If the JavaScript code does not properly handle this event, for example, if it only raises an error and exits:
```javascript
var client = SdkFactory.client();
this.clientReady = new Promise(function(resolve, reject) {
client.once(client.Event.SDK_READY, function() {
resolve();
});
client.once(client.Event.SDK_READY_TIMED_OUT, function() {
reject(new Error("Client SDK Ready Timed Out"));
});
});
```
There are two possible events:
* If the `SDK_READY` event comes first, the promise resolves, and everything works as expected.
* If the `SDK_READY_TIMED_OUT` event comes first, the promise rejects and remains rejected, meaning that any `.catch()` attached will always be called, even if the SDK eventually becomes ready later.
If you add a `.catch()` that does not return or throw an error, the wrapper code might continue executing as if the SDK is ready, even when it is not. For example:
```javascript
this.clientReady.catch(() => {}).then(() => {
});
```
Here, the `.catch()` swallows the error without returning or throwing, causing the promise chain to appear "recovered." This can cause code to run prematurely against an SDK that isn’t ready.
Even if the `SDK_READY_TIMED_OUT` event fires, the SDK might become ready a few milliseconds later and emit the `SDK_READY` event. You should handle these events only when you actually want to respond to them.
1. Allow the SDK to retry fetching treatments a couple of times before giving up, increasing the chance the SDK becomes ready within the timeout:
```javascript
startup: {
requestTimeoutBeforeReady: 5, // 5 seconds
readyTimeout: 5, // 5 seconds
retriesOnFailureBeforeReady: 2, // 2 retries
}
```
2. Configure the SDK to store `Splits` and `mySegments` data in the browser’s `LOCALSTORAGE`. This caches data between page loads and reduces fetch time on subsequent page visits, making the SDK ready faster:
```javascript
storage: {
type: 'LOCALSTORAGE',
prefix: 'MYPREFIX'
},
```
Use a custom prefix to prevent data collision across projects.
For more information, see the [API reference documentation](https://docs.split.io/docs/javascript-sdk-overview#section-configuration).
#### CORS Error in streaming call when running the SDK in a Service Worker
When running the JavaScript SDK inside a Service Worker, the SDK’s streaming HTTP call to `streaming.split.io` can be blocked by the browser’s CORS policy.
A Service Worker acts as a proxy between the browser and the network, intercepting requests and optionally redirecting them to a cache. While this enables offline access, it also means requests (such as the SDK’s Server-Sent Events (SSE) stream) must be explicitly handled in the Service Worker.
If SSE requests are not correctly handled (for example, when adding cache-control headers without accounting for SSE), the streaming connection between the SDK and Split’s backend can fail due to CORS restrictions.
To properly handle SSE streaming connections, add logic to your Service Worker’s `fetch` event listener that detects SSE requests and allows them through.
```javascript
self.addEventListener('fetch', event => {
const { headers, url } = event.request;
const isSSERequest = headers.get('Accept') === 'text/event-stream';
// Only process SSE connections
if (!isSSERequest) return;
const sseHeaders = {
'content-type': 'text/event-stream',
'Transfer-Encoding': 'chunked',
'Connection': 'keep-alive',
};
const sseChunkData = (data, event, retry, id) =>
Object.entries({ event, id, data, retry })
.filter(([, value]) => ![undefined, null].includes(value))
.map(([key, value]) => `${key}: ${value}`)
.join('\n') + '\n\n';
const serverConnections = {};
const getServerConnection = url => {
if (!serverConnections[url]) serverConnections[url] = new EventSource(url);
return serverConnections[url];
};
const onServerMessage = (controller, { data, type, retry, lastEventId }) => {
const responseText = sseChunkData(data, type, retry, lastEventId);
const responseData = Uint8Array.from(responseText, x => x.charCodeAt(0));
controller.enqueue(responseData);
};
const stream = new ReadableStream({
start: controller => getServerConnection(url).onmessage = onServerMessage.bind(null, controller)
});
const response = new Response(stream, { headers: sseHeaders });
event.respondWith(response);
});
```
{% hint style="info" %}
If a default handler is set to `NetworkFirst` (`setDefaultHandler(new NetworkFirst());`), it can prevent the event listener from firing. Removing the default handler resolves this.
{% endhint %}
Alternatively, you can explicitly bypass certain requests in your `fetch` event listener:
```javascript
self.addEventListener('fetch', event => {
// no caching for chrome-extensions
if (event.request.url.startsWith('chrome-extension:')) {
return false;
}
// prevent header striping errors from workbox strategies for EventSource types
if (event.request.url.includes('streaming.split.io')) {
return false;
}
// prevent non-cacheable post requests
if (event.request.method != 'GET') {
return false;
}
// all others, use NetworkFirst workbox strategies
if (strategies) {
const networkFirst = new strategies.NetworkFirst();
event.respondWith(networkFirst.handle({ request: event.request }));
}
});
```
#### "Shared Client not supported by the storage mechanism. Create isolated instances instead" error
When testing the JavaScript SDK browser mode using Jest, it fails with the following error:
```
Shared Client not supported by the storage mechanism. Create isolated instances in stead
```
When using Jest for testing applications, Jest runs in Node.js by default, and Node.js does not support shared clients, which is why it detects the storage does not have that function. It is not possible to overwrite that method from the outside.
You can instruct Jest to explicitly resolve to browser by setting the config in Jest options. For example, when using the `package.json` file, we can add the flag:
```json
{
"name": "MYAPP",
"version": "X.X.X",
...
"jest": {
"browser": true
}
...
}
```
For more information, see the [official Jest documentation](https://jestjs.io/docs/configuration#browser-boolean).
#### Building JavaScript SDK using polymer-cli causes error: ENOENT: no such file or directory
Using the following environment:
* `@polymer/polymer`: 3.1.0
* `polymer-cli`: 1.9.6
Steps to reproduce:
1. Install the SDK: `npm i @splitsoftware/splitio@10.6.0`.
2. Import via ES module:
```js
import { SplitFactory } from '@splitsoftware/splitio';
```
3. Run `polymer build`.
You encounter the following error:
```swift
Error: ENOENT: no such file or directory, open '/Users/[USER_NAME]/projects/[PROJECT_NAME]/frontend/events'
```
Polymer's build process differs from bundlers like webpack. It attempts to load the Node.js path of the SDK, which requires the `events` module, a Node core module unavailable in browser environments.
The SDK package contains both Node and browser versions with:
```json
{
"main": "./node.js",
"browser": "./browser.js"
}
```
While Node.js uses the `main` field (`node.js`), bundlers are instructed to use the browser-specific code (`browser.js`). Polymer’s build does not respect this configuration, leading to the error.
If you plan to implement the JavaScript SDK in both server and browser modes with Polymer, ensure your build configuration properly sets the `browser` and `main` fields to the corresponding JavaScript files to load the correct version.
#### Why does the JavaScript SDK return Not Ready status on slow networks?
When using the JavaScript SDK in a browser, the SDK status often remains as **Not Ready** when users are on a slow network connection (e.g., 3G).
The SDK takes longer to fetch feature flags and segment data from Harness FME servers over slow networks. This delay can cause the SDK to fall back to control treatments since it has not yet completed initialization.
Increase the `startup.readyTimeout` and `startup.requestTimeoutBeforeReady` values to ensure they cover the time needed to fetch FME definitions on slower networks.
1. Measure the fetch duration on a slow network (e.g., using Chrome DevTools to simulate 3G).
2. Enable SDK debug logging in the browser console:
```js
localStorage.splitio_debug = 'on';
```
3. Reload the page and look for the debug line:
```
[TIME TRACKER]: [Fetching - Splits] took xxxx ms to finish
```
Where `xxxx` is the fetch duration in milliseconds.
4. Set the `startup.requestTimeoutBeforeReady` and `startup.readyTimeout` in your SDK initialization to a value higher than the fetch duration, for example:
```js
const sdk = SplitFactory({
startup: {
requestTimeoutBeforeReady: 5000, // 5 seconds
readyTimeout: 5000
}
});
```
5. To reduce network usage, enable local caching of the FME definition by specifying storage when initializing the SDK:
```js
const sdk = SplitFactory({
storage: {
type: 'LOCALSTORAGE',
prefix: 'MYPREFIX'
},
// other config ...
});
```
This configuration ensures the SDK does not have to fetch definitions on every page load, improving readiness on slow or unstable networks.
#### Why does the JavaScript URL return HTTP 404 error?
When using the JavaScript SDK, the following URL request generates a 404 error:
```perl
GET https://sdk.split.io/api/memberships/ 404
```
The URL is missing the required key ID (also known as customer ID). For example, if the key ID is 8879, the URL should be:
```perl
GET https://sdk.split.io/api/memberships/8879
```
Ensure you specify the key or customer ID correctly in the SDK factory initialization and when fetching the client object, for example:
```js
var factory = splitio({
core: {
authorizationKey: 'YOUR_API_KEY',
key: 'CUSTOMER_ID',
trafficType: 'TRAFFIC_TYPE'
}
});
var user_client = factory.client('CUSTOMER_ID', 'TRAFFIC_TYPE');
```
This correctly appends the key ID to the URL and prevents the 404 error.