Split JavaScript SDK

https://github.com/splitio/javascript-client
Admin
The Split SDK for JavaScript enables controlled rollouts and feature flag management in Node.js and...
Tokens:9,195
Snippets:144
Trust Score:9.5
License:Apache-2.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize Split.io SDK

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Initialize the Split.io SDK with your authorization key and customer ID. This is the basic setup required to start using the SDK.

```javascript
var sdk = splitio({
  core: {
    authorizationKey: 'c1l5vkd50gimccout3c03pntbu', // your SDK key
    key: '4a2c4490-ced1-11e5-9b97-d8a25e8b1578'     // your customer id
  }
});
```

--------------------------------

### Instantiate and Use Split SDK in Node.js

Source: https://github.com/splitio/javascript-client/blob/main/README.md

This example demonstrates how to import, instantiate, and use the Split SDK in a Node.js environment. It includes setting up the SDK with an authorization key and listening for the SDK_READY event before fetching feature flag treatments.

```javascript
var SplitFactory = require('@splitsoftware/splitio').SplitFactory;

var factory = SplitFactory({
  core: {
    authorizationKey: 'YOUR_SDK_KEY'
  }
});

var client = factory.client();

client.on(client.Event.SDK_READY, function() {
  var treatment = client.getTreatment('CUSTOMER_ID', 'FEATURE_FLAG_NAME');
  if (treatment == 'on') {
    // insert code here for on treatment
  } else if (treatment == 'off') {
    // insert code here for off treatment
  } else {
    // insert your control treatment code here
  }
});
```

--------------------------------

### TypeScript Type Definitions

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Example demonstrating the use of TypeScript type definitions provided by the Split.io SDK for treatments and browser settings.

```typescript
const myTreatment: SplitIO.Treatment;
const myBrowserSettings: SplitIO.IBrowserSettings;
```

--------------------------------

### Get Treatment with Attributes

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Retrieve a feature treatment for a given user key and attributes. The attributes are used for targeting rules.

```javascript
var treatment = sdk.getTreatment('my_feature', {
  age: 24,
  likes: ['apple', 'orange'],
  dob: new Date('1991-05-22').getTime()
});
```

--------------------------------

### Get Treatments with Multiple Flags

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Retrieve the status of multiple feature flags for a given customer key using the getTreatments method. This returns a map of flag names to their treatments.

```javascript
var treatmentsMap = client.getTreatments('CUSTOMER_KEY', ['Feature_flag_1', 'Feature_flag_2']);

/*
* treatmentsMap will be an object mapping feature flags with treatments. For example:
* {
*   Feature_flag_1: 'on',
*   Feature_flag_2: 'off
* }
*/
```

--------------------------------

### Instantiate and Manage Multiple SDK Instances

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Demonstrates how to create, use, and destroy multiple independent Split.io SDK instances in a browser. Useful for applications with distinct user contexts.

```html
<script src="//cdn.split.io/sdk/split-5.0.0.min.js"></script>
<script>
  // instantiation
  var dynamic1 = splitio({
    core: {
      authorizationKey: '<your-token>',
      key: 'myuser@domain.com'
    }
  });

  var dynamic2 = splitio({
    core: {
      authorizationKey: '<your-token>',
      key: 'annoy@domain.com'
    }
  });

  // usage
  var t1 = dynamic1.getTreatment('feature-flag-name');
  var t2 = dynamic2.getTreatment('another-feature-flag-name');

  // stop SDK
  dynamic1.destroy();
  dynamic2.destroy();

  // unreference
  dynamic1 = null;
  dynamic2 = null;
</script>
```

--------------------------------

### Configure SDK Startup Behavior

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Configure startup timeouts, retries, and event listeners for the Split.io SDK in a browser environment. Useful for managing SDK readiness.

```html
<script src="//cdn.split.io/sdk/split-6.0.0.min.js"></script>
<script>
  var sdk = splitio({
    core: {
      authorizationKey: '<your-token>',
      key: 'myuser@domain.com'
    },
    startup: {
      // timeout an *initial* request after 0.8 seconds (only affects startup)
      requestTimeoutBeforeReady: 0.8,
      // how many quick retries are allowed before use the schedulers refresh
      // rates (only affects startup)
      retriesOnFailureBeforeReady: 1,
      // maximum amount of seconds we are going to wait for the ready event
      readyTimeout: 1.5
    }
  });

  sdk.on(sdk.Event.SDK_READY_TIMED_OUT, function () {
    // this callback will be called after 1.5 seconds if and only if the SDK
    // is not ready for that time
  });

  sdk.on(sdk.Event.SDK_READY, function () {
    // the SDK is ready for start making evaluations with your data
  });

  sdk.on(sdk.Event.SDK_UPDATE, function () {
    // fired each time the SDK state change
  });
</script>
```

--------------------------------

### Configure Split.io SDK for Development Mode (v4+)

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Configure the Split.io SDK using an authorization key for development mode in versions 4 and later. This replaces the previous method of switching URLs.

```html
<script src="https://cdn.split.io/sdk/split-4.0.0.js"></script>
<script>
  var sdk = splitio({
    core: {
      authorizationKey: 'localhost'
    },
    features: {
      feature_name_1: 'treatment_value_1',
      feature_name_2: 'treatment_value_2',
      ...
    }
  });
</script>
```

--------------------------------

### Storage Wrapper Configuration

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Information on configuring a custom storage wrapper for the Split.io SDK, particularly for the LOCALSTORAGE type.

```APIDOC
## Storage Wrapper Configuration

### `storage.wrapper` Configuration Option

#### Description
Allows the SDK to use a custom storage wrapper when the storage type is set to `LOCALSTORAGE`. The default value for this wrapper is `window.localStorage`. This provides flexibility in how client-side storage is managed.
```

--------------------------------

### Enable Debugging via Settings

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Enable SDK logs by setting the 'debug' option to true when instantiating the SDK. This is useful for troubleshooting.

```javascript
var splitio = require('@splitsoftware/splitio');

var settings = {
  core: {
    authorizationKey: 'YOUR_SDK_KEY',
    key: 'CUSTOMER_KEY'  // If on the browser.
  },
  debug: true  // Boolean flag for enabling logs. Default value is false.
};

var sdk = splitio(settings);
```

--------------------------------

### Handle SDK Ready and Update Events

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Register event listeners for SDK readiness and updates in a browser environment. Useful for reacting to SDK state changes.

```html
<script src="//cdn.split.io/sdk/split-5.0.0.min.js"></script>
<script>
  var sdk = splitio({
    core: {
      authorizationKey: '<your-token>',
      key: 'myuser@domain.com'
    }
  });

  sdk.on(sdk.Event.SDK_READY, function sdkReadyEvent() {
    // This event will be fired once
  });

  sdk.on(sdk.Event.SDK_UPDATE, function sdkUpdateEvent() {
    // This event will be fired each time the SDK downloads an update
  });
</script>
```

--------------------------------

### Recommended Scheduler Refresh Rates

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Set recommended values for scheduler refresh rates in seconds. These values balance performance and data freshness.

```javascript
scheduler: {
  featuresRefreshRate:    30, // in 2.x 30 sec, in 1.x 60000 milliseconds (1min)
  segmentsRefreshRate:    60, // in 2.x 60 sec, in 1.x 60000 milliseconds (1min)
  metricsRefreshRate:     60, // in 2.x 60 sec, in 1.x 300000 milliseconds (5min)
  impressionsRefreshRate: 60  // in 2.x 60 sec, in 1.x 300000 milliseconds (5min)
}
```

--------------------------------

### Configure Split.io SDK for Development Mode (v3 and earlier)

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Configure the Split.io SDK for development mode using a specific offline script in versions 3 and earlier. This method is now deprecated.

```html
<script src="https://cdn.split.io/sdk/offline-3.0.0.js"></script>
<script>
  var sdk = splitio({
    features: {
      feature_name_1: 'treatment_value_1',
      feature_name_2: 'treatment_value_2',
      ...
    }
  });
</script>
```

--------------------------------

### Browser LocalStorage Backend Configuration

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Configure the Split.io SDK in the browser to use LocalStorage as a backend. This can significantly improve the 'ready' event performance by quickly reloading data.

```javascript
const config = {
  core: {
    authorizationKey: '<your-api-token>',
    key: '<user-key>'
  },
  storage: {
    type: 'LOCALSTORAGE'
  }
};

const factory = splitio(config);
const client = factory.client();

const treatment = client.getTreatment('my-feature-comming-from-localstorage');
```

--------------------------------

### Standalone Client-Side SDK Configuration

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Configuration options for the standalone client-side (Browser) Split.io SDK.

```APIDOC
## Standalone Client-Side SDK Configuration

### `initialRolloutPlan` Configuration Option

#### Description
Allows preloading the SDK storage with a snapshot of the rollout plan for the standalone client-side SDK. This can improve initial load performance by providing feature flag data immediately.
```

--------------------------------

### Client Status and Readiness

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Provides methods to check the current status and readiness of the Split.io client. These are essential for understanding when the SDK is ready to serve feature flags.

```APIDOC
## Client Status and Readiness Methods

### `client.getStatus()`

#### Description
Retrieves the current readiness status properties of the Split.io client. This includes properties like `isReady`, `isReadyFromCache`, etc.

### `client.whenReady()`

#### Description
Returns a promise that resolves when the Split.io client is ready. This is the recommended method for checking readiness, especially when using async/await.

### `client.whenReadyFromCache()`

#### Description
Returns a promise that resolves when the Split.io client is ready from cache. This is useful for scenarios where you need to ensure the client has loaded from a cached state.
```

--------------------------------

### Browser SDK Migration Script

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Include this script in the browser to use the new SDK API while allowing for a gradual migration from older versions.

```html
<script src="//cdn.split.io/sdk/split-migration-8.0.0.min.js"></script>
```

--------------------------------

### Custom Logger Configuration

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Details on how to configure and use custom loggers with the Split.io SDK for enhanced logging capabilities.

```APIDOC
## Custom Logger Configuration

### `factory.Logger.setLogger(customLogger)`

#### Description
Allows the SDK to use a custom logger instance. This method enables integration with existing logging frameworks or custom logging solutions.

### `startup.logger` Configuration Option

#### Description
An option that can be provided during SDK initialization to specify a custom logger. This logger will be used by the SDK for all its internal logging.
```

--------------------------------

### Standalone Server-Side SDK Methods

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Methods available for the standalone server-side (Node.js) Split.io SDK.

```APIDOC
## Standalone Server-Side SDK Methods

### `factory.getRolloutPlan()`

#### Description
Retrieves the rollout plan snapshot from the storage for the standalone server-side SDK. This allows server-side applications to access feature flag rollout information.
```

--------------------------------

### Node.js SDK Migration Module

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Require the migration module in Node.js environments to use the new SDK API during a transition period.

```javascript
var sdk = require('@splitsoftware/splitio/migration');
```

--------------------------------

### Node.js Redis Storage Configuration

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Configure the Split.io SDK in Node.js to use Redis for storage, enabling consistency across multiple SDK instances. Requires specifying the storage type and connection options.

```javascript
const SplitFactory = require('@splitsoftware/splitio');
const config = {
  mode: 'consumer',
  core: {
    authorizationKey: '<your-api-token>'
  },
  storage: {
    type: 'REDIS',
    options: {
      url: 'redis://<your-redis-server>:<your-redis-server-port>/0'
    },
    prefix: 'nodejs' // Optional prefix to prevent any kind of data collision between SDK versions.
  }
};

const client = SplitFactory(config);

// Redis in Node.js is async so we can use async/await syntax
const treatment = await client.getTreatment('my-feature-coming-from-localstorage');

// or just use the returned promise
client.getTreatment('my-feature-coming-from-localstorage').then(treatment => {
  // do something with the treatment
});
```

--------------------------------

### Configure Refresh Rates (Milliseconds to Seconds)

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Update scheduler configuration to change refresh rates from milliseconds to seconds. This is a breaking change introduced in version 2.0.0.

```javascript
var sdk = splitio({
  core: {
    authorizationKey: 'c1l5vkd50gimccout3c03pntbu', // your SDK key
    key: '4a2c4490-ced1-11e5-9b97-d8a25e8b1578'     // your customer id
  },
  scheduler: {
    featuresRefreshRate:    60, // in 2.x 60 sec, in 1.x 60000 milliseconds
    segmentsRefreshRate:    60, // in 2.x 60 sec, in 1.x 60000 milliseconds
    metricsRefreshRate:     30, // in 2.x 30 sec, in 1.x 30000 milliseconds
    impressionsRefreshRate: 30  // in 2.x 30 sec, in 1.x 30000 milliseconds
  }
});
```

--------------------------------

### Configure Offline Changes Refresh Rate

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Set the rate at which the SDK updates its internal state when offline. Useful for Node.js development.

```javascript
const config = {
  core: {
    authorizationKey: '<your-api-token>',
    key: '<user-key>'
  },
  scheduler: {
    offlineRefreshRate: 15 // update internal SDK state each 15 sec
  },
  features: {
    mySplit: 'on'
  }
};

const factory = splitio(config);
const client = factory.client();

await client.ready();

client.getTreatment('my_feature') === 'on'; // true

factory.settings.features.my_feature = 'off'; // Apply this cache programmatically

client.getTreatment('my_feature') === 'off'; // Some time after you will be able to verify this
```

--------------------------------

### Update trafficType handling in Browser SDK

Source: https://github.com/splitio/javascript-client/blob/main/MIGRATION-GUIDE.md

In v11.0.0, the `trafficType` configuration option and parameter are removed. Provide the traffic type in the `client.track` method instead.

```javascript
// JS SDK v10.x.x
const factory = SplitFactory({
  core: {
    authorizationKey: '...', 
    key: USER_KEY,
    trafficType: 'user'
  }
});

const client = factory.client();
const accountClient = factory.client(ACCOUNT_ID, 'account');

client.track('my_event');
accountClient.track('my_event');
```

```javascript
// JS SDK v11.0.0
const factory = SplitFactory({
  core: {
    authorizationKey: '...', 
    key: USER_KEY
  }
});

const client = factory.client();
const accountClient = factory.client(ACCOUNT_ID);

client.track('user', 'my_event');
accountClient.track('account', 'my_event');
```

--------------------------------

### Enable/Disable SDK Logger API

Source: https://github.com/splitio/javascript-client/blob/main/CHANGES.txt

Control SDK logging directly using the Logger API. This allows enabling or disabling logs without re-instantiating the SDK.

```javascript
var splitio = require('@splitsoftware/splitio');

var sdk = splitio({
  core: {
    authorizationKey: 'YOUR_SDK_KEY',
    key: 'CUSTOMER_KEY'  // If on the browser.
  }
});

// Logger API.
sdk.Logger.enable();
sdk.Logger.disable();
```
Tokens:
Raw