Skip to main content

Browser SDK migration guide

Refer to this document to check API differences and migration details for moving from JavaScript SDK v10.15.x using NPM or Github to Browser SDK v0.1.x using NPM or Github.

Requirements​

Browser SDK has the same browser requirements as JavaScript SDK (it supports ES5 syntax and requires Promises support) but also requires Fetch API support.

Therefore, to target old browsers such as IE10, users must polyfill the Fetch API besides Promises. More details here.

Installation and import​

JavaScript SDK 10.15.xBrowser SDK 0.1.x
Install NPM package> npm install @splitsoftware/splitio> npm install @splitsoftware/splitio-browserjs
Import with ES6 module syntaximport { SplitFactory } from ‘@splitsoftware/splitio’import { SplitFactory } from ‘@splitsoftware/splitio-browserjs’
Import with CommonJSconst { SplitFactory } = require( ‘@splitsoftware/splitio’)const { SplitFactory } = require( ‘@splitsoftware/splitio-browserjs’)
Install with CDN script tag<script src="//cdn.split.io/sdk/split-10.15.4.min.js"></script>Two variants are available at the moment:
Slim/Regular version:
<script src="//cdn.split.io/sdk/split-browser-0.1.0.min.js"></script>
Full version: regular + pluggable modules (InLocalStorage, integrations and loggers)
<script src="//cdn.split.io/sdk/split-browser-0.1.0.full.min.js"></script>
Instantiate with CDNvar factory = splitio({...})var factory = splitio({...}) or var factory = splitio.SplitFactory({...})

Configuration and API​

Most configuration params are the same in JavaScript SDK and Browser SDK. SDK client and manager APIs (i.e., method signatures) are also the same. The differences:

Traffic type​

JavaScript SDK 10.15.xBrowser SDK 0.1.x
Clients can be bound to a traffic type to track events without the need to pass the traffic type. 
var factory = SplitFactory({
core: {
   authorizationKey: 'YOUR_API_KEY',
   key: 'USER_ID',
   trafficType: 'YOUR_CUSTOMER_TRAFFIC_TYPE'
 }
});

// Must not pass traffic type to track call if provided on the factory settings

var mainClient = factory.client();
mainClient.track('EVENT_TYPE', eventValue);

// or when creating a new client with a traffic type.

var newClient = factory.client('NEW_KEY', 'NEW_TRAFFIC_TYPE');
newClient.track('EVENT_TYPE', eventValue);
Clients cannot be bound to a traffic type, so for tracking events we always need to pass the traffic type. This simplifies the track method signature, by removing ambiguity of when it should receive the traffic type or not.

Bucketing key​

Bucketing key support was removed from Browser SDK. So passing an object as a key is not allowed:

var factory = SplitFactory({
 core: {
   authorizationKey: 'YOUR_API_KEY',

   // NOT SUPPORTED: key must be a string
   key: { matchingKey: 'YOUR_MATCHING_KEY', bucketingKey: 'YOUR_BUCKETING_KEY' }
 }
});

// NOT SUPPORTED: key must be a string
var newClient = factory.client({ matchingKey: 'NEW_MATCHING_KEY', bucketingKey: 'NEW_BUCKETING_KEY' });

Pluggable modules​

Some configuration params are based on pluggable modules now, in favor of size reduction.

When using ES module imports, the pluggable modules that are not imported are not included in the final output build.

The impact of each module on the final bundle size is roughly estimated in the Export Analysis section of Bundlephobia entry.

Importing pluggable modules with ES module imports:

import {
 SplitFactory,
 // Pluggable modules:
 ErrorLogger, WarnLogger, InfoLogger, DebugLogger,
 InLocalStorage, GoogleAnalyticsToSplit, SplitToGoogleAnalytics }
from '@splitsoftware/splitio-browserjs';

When using CDN script tags, you can opt for using the regular/slim version without pluggable modules or the full one with them.

Accessing pluggable modules with the full CDN bundle (they are not available on the slim version):

const {
 SplitFactory,
 // Pluggable modules:
 ErrorLogger, WarnLogger, InfoLogger, DebugLogger,
 InLocalStorage, GoogleAnalyticsToSplit, SplitToGoogleAnalytics }
= window.splitio;

Logging​

In the Browser SDK, you must “plug” a logger instance in the debug config param to have human-readable message codes.

You can set a boolean or string log level value as debug config param, as in the regular JavaScript SDK, but in that case, most log messages will display a code number instead.

Those message codes are listed in the public repository: Error, Warning, Info, Debug. More details here.

JavaScript SDK 10.15.xBrowser SDK 0.1.x
import { SplitFactory } from '@splitsoftware/splitio'

var factory = SplitFactory({
 …,
 debug: 'DEBUG' // other options are: true, false,
                // 'INFO', 'WARN' and 'ERROR'
});
import { SplitFactory, DebugLogger } from '@splitsoftware/splitio-browserjs'

var factory = SplitFactory({
 …,
 debug: DebugLogger() // other options are: true, false, 'DEBUG',
                      // 'INFO', 'WARN', 'ERROR', InfoLogger(),
                      // WarnLogger(), and ErrorLogger()
});

Configuring LocalStorage​

JavaScript SDK 10.15.xBrowser SDK 0.1.x
import { SplitFactory } from '@splitsoftware/splitio'

var sdk = SplitFactory({
 core: {
   authorizationKey: 'YOUR_API_KEY',
   key: 'USER_ID',
 },

 storage: {
   type: 'LOCALSTORAGE',
   prefix: 'MYPREFIX'
 }
});
import {
  SplitFactory,
  InLocalStorage 
} from '@splitsoftware/splitio-browserjs'

var sdk = SplitFactory({
 core: {
   authorizationKey: 'YOUR_API_KEY',
   key: 'USER_ID',
 },

 storage: InLocalStorage({
   prefix: 'MYPREFIX'
 })
});

Additional Notes​

CDN bundle size:

NPM package size: