Skip to main content

Browser SDK Migration Guide

Overview​

This guide covers the key differences and migration details when moving from JavaScript SDK v10.15.x (via NPM or GitHub) to Browser SDK v0.1.x (via NPM or GitHub).

Requirements​

The Browser SDK supports the same browsers as the JavaScript SDK (ES5 syntax and Promises), but additionally requires Fetch API support.

To target older browsers like IE10, you must polyfill the Fetch API alongside Promises.

Installation and Import​

JavaScript SDK 10.15.xBrowser SDK 0.1.x
Install NPM package:Install NPM package:
npm install @splitsoftware/splitionpm install @splitsoftware/splitio-browserjs
Import with ES6 module syntax:Import with ES6 module syntax:
import { SplitFactory } from '@splitsoftware/splitio'import { SplitFactory } from '@splitsoftware/splitio-browserjs'
Import with CommonJS:Import with CommonJS:
const { SplitFactory } = require('@splitsoftware/splitio')const { SplitFactory } = require('@splitsoftware/splitio-browserjs')
Install with CDN script tag:Install with CDN script tag (two variants):
<script src="//cdn.split.io/sdk/split-10.15.4.min.js"></script>Slim/Regular: <script src="//cdn.split.io/sdk/split-browser-0.1.0.min.js"></script>
Full (includes pluggable modules): <script src="//cdn.split.io/sdk/split-browser-0.1.0.full.min.js"></script>

Instantiate with CDN:

// JavaScript SDK
var factory = splitio({...});

// Browser SDK
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: