Electron SDK reference

Overview

This reference guide documents the LaunchDarkly SDK for the Electron desktop application framework. This is a variant of the client-side JavaScript SDK with additional functionality for Electron.

LaunchDarkly's SDKs are open source. To learn more, read Electron SDK GitHub repository. It also makes use of code from the JavaScript SDK repository. The online API docs contain the programmatic definitions of every type and method. You can also try this SDK out by cloning and running a sample application.

Why use this instead of the Node.js SDK?

Since Electron is based on Node.js, it is possible to run the LaunchDarkly Node SDK in it. However, this is strongly discouraged because the Node.js SDK is meant for server-side use, not for applications that are distributed to users. There are several reasons why this distinction matters:

• The server-side SDKs include an SDK key that can download the entire definition (including rollout rules and individual user targets) of all of your feature flags. If you embed this SDK key in an application, any user who looks inside the application can then access all of your feature flag definitions—which may include sensitive data such as other users' email addresses. The client-side and mobile SDKs use different credentials that do not allow this.
• The server-side SDKs do in fact download your entire flag data using this key, since they have to be able to evaluate flags quickly for any user. That can be quite a large amount of data. The client-side and mobile SDKs, which normally evaluate flags for just one user at a time, use a much more efficient protocol where they request only the active variation for each flag for that specific user.
• The Electron SDK also includes features that are specific to Electron, such as the ability to access main-process flags from the front end as described below.

Server-side Node SDK compatibility

For developers who were using the server-side Node.js in Electron before the Electron SDK was available, there are differences between the APIs that can be inconvenient. For instance, in the server-side Node SDK, variation() is an asynchronous call that takes a callback, whereas in the client-side SDKs it is synchronous.

To make this transition easier, the LaunchDarkly Electron SDK provides an optional wrapper that emulates the Node.js SDK. When creating the main-process client, after calling initializeInMain, pass the client object to createNodeSdkAdapter. The resulting object uses the Node-style API.

Here's how to create the wrapper:

1var realClient = LDElectron.initializeInMain('YOUR_CLIENT_SIDE_ID', user, options);
2
3var wrappedClient = LDElectron.createNodeSdkAdapter(realClient);
4
5wrappedClient.waitForInitialization().then(function() {
6  wrappedClient.variation(flagKey, user, defaultValue, function(err, result) {
7    console.log('flag value is ' + result);
8  });
9});
COPY

The underlying implementation is still the client-side SDK, which has a single-current-user model. Therefore, when you call client.variation(flagKey, user, defaultValue) it is really calling client.identify(user) first, obtaining flag values for that user, and then evaluating the flag. This performs poorly if you attempt to evaluate flags for a variety of different users in rapid succession.

Known issues in this release

Known issues include:

• If you are using the normal pattern of configuring your LaunchDarkly client in the main process, and then using initializeInRenderer() to get a mirror of the client in a renderer process, the client instance in the renderer process will not allow you to call identify() to change the current user. The current user can only be set in the main process. This may or may not change in future versions.
• When the main process receives new feature flag values from LaunchDarkly, they should be sent to the renderer processes automatically; however, there was one report of this not working, i.e. the renderer process continued to have the old flag values. Please let us know if you see any such problems.

Getting started

After you complete the Getting Started process, follow these instructions to start using the LaunchDarkly SDK in your Electron code.

You can install the SDK into your Electron project using npm:

1npm install --save launchdarkly-electron-client-sdk
2
3# In earlier versions, the package name was ldclient-electron
COPY

Initializing the client

Every Electron application consists of a main process, which is similar to a Node.js application, and some number of renderer processes, each of which is a Chromium web browser with its own window. These processes have their own independent JavaScript engines and data spaces, although there are ways to communicate between them.

The LaunchDarkly Electron SDK is designed to use LaunchDarkly feature flags from within any of these processes. In the normal use case, there is an SDK client running in the main process; the renderer processes can then create client instances that are in effect mirrors of the main one.

To set up the main process client, you need the client-side ID for your LaunchDarkly environment, an object containing user properties (although you can change the user later), and optional configuration properties. Your client-side ID is available in the Projects tab of your account settings page. Be sure to use a client-side ID. Client-side IDs are not secret and you can expose them in your client-side code without risk. Never embed a server-side SDK key into a client-side application.

To initialize the client:

1const LDElectron = require('launchdarkly-electron-client-sdk');
2
3const user = { key: 'example' };
4const options = {};
5const client = LDElectron.initializeInMain('YOUR_CLIENT_SIDE_ID', user, options);
COPY

In a renderer process, to create a client object that uses the same feature flag data, you only need to do this:

1const LDElectron = require('launchdarkly-electron-client-sdk');
2
3const client = LDElectron.initializeInRenderer();
COPY

This gives you an object with the same interface—so you can evaluate feature flags, listen for flag change events, etc., in exactly the same way in the main process and the renderer process. However, only the main-process client is actually communicating with LaunchDarkly; the renderer-process clients are just delegating to the main one. This means that the overhead per application window is minimal, although it is still a good idea to retain a single client instance per window, rather than creating them ad-hoc when you need to evaluate a flag.

Both types of client are initialized asynchronously, so if you want to determine when the client is ready to evaluate feature flags, use the ready event or waitForInitialization():

1// using an event listener:
2client.on('ready', function() {
3  // now we can evaluate some feature flags
4});
5
6// or, using a Promise:
7client.waitForInitialization().then(function() {
8  // now we can evaluate some feature flags
9});
COPY

If you try to evaluate feature flags before the client is ready, it will behave as it would if no flags existed (for example,variation returns a default value).

Lastly, shut down the client when your application terminates. To learn more, read Shutting down.

To learn more about the specific configuration options that are available in this SDK, read the SDK's API docs.

Supported features

This SDK supports the following features:

• Aliasing users
• Bootstrapping
• Evaluating flags
• Identifying and changing users
• Logging configuration
• Monitoring SDK status
• Sending custom events
• Shutting down
• Subscribing to flag changes