1. Split Help Center
  2. Installing the SDK
  3. FAQs: Client-side SDKs

Browser SDK migration guide

  • Updated

Refer to this document to check API differences and migration details for moving from

JS SDK v10.15.x  using NPM or Github to JS Browser SDK v0.1.x using NPM or Github. 

Requirements

JS Browser SDK has the same browser requirements as JS 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

 

JS SDK 10.15.x

JS Browser SDK 0.1.x

Install NPM package

> npm install @splitsoftware/splitio

> npm install @splitsoftware/splitio-browserjs

Import with ES6 module syntax

import { SplitFactory } from ‘@splitsoftware/splitio’

import { SplitFactory } from ‘@splitsoftware/splitio-browserjs’

Import with CommonJS

const { 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>

2 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 CDN

var factory = splitio({...})

var factory = splitio({...}) // or ...
var factory = splitio.SplitFactory({...})

 

Configuration and API

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

Traffic type

JS SDK 10.15.x

JS Browser SDK 0.1.x

Clients can be bound to a traffic type to track events without the need to pass the traffic type.

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.

var factory = SplitFactory({

 core: {

   authorizationKey: 'YOUR_API_KEY',

   key: 'YOUR_KEY'

 }

});

 

// Need to pass traffic type when tracking events.

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

queued = factory.client('KEY_FOR_NEW_CLIENT').track('TRAFFIC_TYPE', 'EVENT_TYPE', eventValue);

var factory = SplitFactory({

 core: {

   authorizationKey: 'YOUR_API_KEY',

   key: 'YOUR_KEY',

   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);

NOT ALLOWED


The `core.trafficType` config param, and the second param of `factory.client()` are ignored.

Bucketing key

Bucketing key support was removed from JS 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 JS 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 JS 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.

JS SDK 10.15.x

JS Browser 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

JS SDK 10.15.x

JS Browser SDK 0.1.x

import { SplitFactory } from
'@splitsoftware/splitio'

 

var sdk = SplitFactory({

 core: {

   authorizationKey: 'YOUR_API_KEY',

   key: 'YOUR_KEY',

 },

 storage: {

   type: 'LOCALSTORAGE',

   prefix: 'MYPREFIX'

 }

});

import { SplitFactory, InLocalStorage } from '@splitsoftware/splitio-browserjs'

 

var sdk = SplitFactory({

 core: {

   authorizationKey: 'YOUR_API_KEY',

   key: 'YOUR_KEY',

 },

 storage: InLocalStorage({

   prefix: 'MYPREFIX'

 })

});

 

Configuring integrations

JS SDK 10.15.x

JS Browser SDK 0.1.x

import { SplitFactory } from '@splitsoftware/splitio'

 

var factory = SplitFactory({

 core: {

   authorizationKey: 'YOUR_API_KEY',

   key: 'YOUR_KEY',

 },

 integrations: [

   {

     type: 'GOOGLE_ANALYTICS_TO_SPLIT',

     identities: [{

       key: 'YOUR_KEY',

       trafficType: 'user'

     }]

   }, {

     type: 'SPLIT_TO_GOOGLE_ANALYTICS'

   }

 ]

});

import { SplitFactory, GoogleAnalyticsToSplit, SplitToGoogleAnalytics } from '@splitsoftware/splitio-browserjs'

 

var factory = SplitFactory({

 core: {

   authorizationKey: 'YOUR_API_KEY',

   key: 'YOUR_KEY'

 },

 integrations: [

   GoogleAnalyticsToSplit({

     identities: [{

       key: 'YOUR_KEY',

       trafficType: 'user'

     }]

   }),

   SplitToGoogleAnalytics()

 ]

});

 

Localhost mode

Not supported.  Split hasn’t yet decided how to expose this feature as a pluggable module in favor of size reduction.

JS SDK 10.15.x

JS Browser SDK 0.1.x

var sdk = SplitFactory({

 core: {

   authorizationKey: 'localhost'

 },

 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

 }

});

NOT SUPPORTED YET

 

Additional Notes

CDN bundle size:

NPM package size:

Related articles

Comments

0 comments

Please sign in to leave a comment.