Skip to main content

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 Harness servers, for exposure in the Harness FME 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 Harness 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 Harness servers and write them into the storage.
  • Post impressions: Send to Harness servers the stored impressions generated by the SDKs.
  • Post events: Send to Harness 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

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

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:

ConfigurationDescriptionDefault value
scheduler.impressionsPerPostMaximum number of impressions to send per POST request.1000
scheduler.eventsPerPostMaximum number of events to send per POST request.1000
scheduler.maxRetriesMaximum number of retry attempts for posting impressions and events.3
sync.flagSpecVersionThe version of the feature flag definitions to be fetched and stored.1.1
sync.splitFiltersList of filter objects to granularly control which feature flags are synced into the storage. This is formed by a type string property and a list of string values for the given criteria. Using the types 'bySet' (recommended, flag sets are available in all tiers) or 'byName', pass an array of strings defining the query. If empty or unset, all feature flags are synced.[]
sync.impressionsModeThis configuration defines how impressions extracted from the storage are pre-processed before being sent to Harness servers. Supported modes are OPTIMIZED and DEBUG. In OPTIMIZED mode, only unique impressions are queued and posted to Harness. In DEBUG mode, ALL impressions are queued and sent to Harness. Use DEBUG mode when you want every impression to be logged in the Harness FME when trying to debug your setup.OPTIMIZED
sync.requestOptions.agentA custom Node.js HTTP(S) Agent used to perform the requests to the Harness servers. Go to the Proxy section for details.undefined
storage.prefixAn optional prefix for your data, to avoid collisions if using the same storage for multiple SDK keys.SPLITIO
debugEither a boolean flag or a log level string ('ERROR', 'WARN', 'INFO', or 'DEBUG') for activating Synchronizer logs.false

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

Proxy​

If you need to use a network proxy, you can provide a custom Node.js HTTPS Agent by setting the sync.requestOptions.agent configuration variable. The Synchronizer will use this agent to perform requests to Harness servers.

// Install with `npm install https-proxy-agent`
const { HttpsProxyAgent } = require('https-proxy-agent');
const { Synchronizer } = require('@splitsoftware/splitio-sync-tools');

const proxyAgent = new HttpsProxyAgent(process.env.HTTPS_PROXY || 'http://10.10.1.10:1080');

const synchronizer = new Synchronizer({
  ...
  sync: { 
    requestOptions: { 
      agent: proxyAgent 
    } 
  }
});

Examples​

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