Split JavaScript synchronizer tools

This guide provides detailed information about our Split JavaScript Sync Tools library. All of our SDKs and libraries are open source. Refer to our Split JavaScript Sync Tools GitHub repository to see the source code.

Split sync tools is an NPM package that includes the JavaScript Synchronizer. This synchronizer coordinates the sending and receiving of data to a remote datastore that all of your processes can share to pull data for the evaluation of treatments. Out of the box, the SDKs pluggable feature allows them to connect to a remote datastore, and so the JavaScript Synchronizer uses same datastore as the cache for your SDKs when it evaluates treatments. It also posts impression and event data and metrics generated by the SDKs back to Split servers, for exposure in the Split user interface or sending it to the data integration of your choice.

Language Support

Split sync tools supports Node.js version 8 or later. To run the tools in other JavaScript environments, the target environment must support modern ES6 (ECMAScript 2015) syntax, and provide built-in support or a global polyfill for Promises and Web Fetch API.

If you're looking for possible polyfill options, for Promise, refer to es6-promise and for Fetch, refer to the lightweight unfetch or whatwg-fetch.

Overall Architecture

JavaScript Synchronizer executes as a single run script which performs the following actions:

• Fetch feature flags: Retrieve your feature flag definitions from Split servers and write them into the storage. Keep in mind that you can use filters to granularly control which feature flags are synced into the storage. See the Configuration section for more details.
• Fetch segments: Retrieve your set segments lists from Split servers and write them into the storage.
• Post impressions: Send to Split servers the stored impressions generated by the SDKs.
• Post events: Send to Split servers the stored events generated by the SDKs .track method.

Unlike the Split Go Synchronizer, the JavaScript Synchronizer executes as an script in a compatible JavaScript runtime environment like Node.js.

Initialization

Set up the synchronizer in your code base with the following two steps:

1. Install the library in your project

The library is published using npm, so you can install it in your project with an NPM package manager.

npm install --save @splitsoftware/splitio-sync-tools

yarn add @splitsoftware/splitio-sync-tools

2. Import, instantiate, and execute the Synchronizer

const { Synchronizer } = require('@splitsoftware/splitio-sync-tools');

const synchronizer = new Synchronizer({
  core: {
    authorizationKey: 'YOUR_SDK_KEY'
  },
  storage: {
    // Wrapper object must implement the interface used by the Synchronizer to read and write data into an storage
    wrapper: MyStorageWrapper
  }
});

synchronizer.execute().then(() => { 
  console.log('Single-run synchronization finished');
});

import { Synchronizer } from '@splitsoftware/splitio-sync-tools';

const synchronizer = new Synchronizer({ 
  core: {
    authorizationKey: 'YOUR_SDK_KEY'
  },
  storage: {
    // Wrapper object must implement the interface used by the Synchronizer to read and write data into an storage
    wrapper: MyStorageWrapper
  }
});

await synchronizer.execute();

console.log('Single-run synchronization finished');

Configuration

The JavaScript synchronizer has a number of knobs for configuring performance. Each knob is tuned to a reasonable default. However, you can override the values while instantiating the synchronizer. The parameters available for configuration are described below:

To set each of the parameters defined above, use the following syntax:

const synchronizer = new Synchronizer({
  core: {
    authorizationKey: 'YOUR_SDK_KEY'
  },
  scheduler: {
    impressionsPerPost: 1000,
    eventsPerPost: 1000,
    maxRetries: 3
  },
  sync: {
    splitFilters: [{
      type: 'bySet',
      values: ['backend', 'server_side']
    }],
    impressionsMode: 'DEBUG'
  },
  storage: {
    prefix: 'MYPREFIX',
    wrapper: MyStorageWrapper
  },
  debug: true
});

Examples

This section contains a list of examples of wrapper implementations for different remote datastores that can be used with JavaScript Synchronizer.

• Cloudflare Workers template