DevCycle NodeJS Server SDK

The NodeJS Server SDK for DevCycle.

This SDK uses local bucketing to perform all user segmentation and bucketing locally in the SDK, providing immediate responses to variable and feature requests for a user.

The SDK will download the latest version of your DevCycle environments configuration from a CDN on initialization, and will periodically poll the CDN for configuration changes.

The SDK is available as a package on npm. It is also open source and can be viewed on Github.

Installation

Our library can be found on npm and installed by the following:

npm install --save @devcycle/nodejs-server-sdk

Getting Started

To use the DVC Server SDK in your project, import the @devcycle/nodejs-server-sdk package and call initialize with your DVC environment server key. You may optionally await for the client to be initialized.

JS Example:

const DVC = require('@devcycle/nodejs-server-sdk')

const dvcClient = await DVC.initialize('<DVC_ENVIRONMENT_SERVER_KEY>').onClientInitialized()

Typescript Example:

import { initialize } from '@devcycle/nodejs-server-sdk'

const dvcClient = await initialize('<DVC_ENVIRONMENT_SERVER_KEY>').onClientInitialized()

Usage

Initialization Options

The SDK exposes various initialization options which can be set on the initialization() method:

DVCOptions Typescript Schema

const dvcClient = await DVC.initialize('<DVC_ENVIRONMENT_SERVER_KEY>', {
    configPollingIntervalMS: 60 * 1000
}).onClientInitialized()

DVC Option	Type	Description
logger	DVCLogger	Logger override to replace default logger
logLevel	String	Set log level of the default logger. Options are: debug, info, warn, error. Defaults to info.
enableCloudBucketing	Boolean	Switches the SDK to use Cloud Bucketing (via the DevCycle Bucketing API) instead of Local Bucketing.
enableEdgeDB	Boolean	Enables the usage of EdgeDB for DevCycle that syncs User Data to DevCycle. NOTE: This is only available with Cloud Bucketing.
configPollingIntervalMS	Number	Controls the polling interval in milliseconds to fetch new environment config changes, defaults to 10 seconds, minimum value is 1 second.
configPollingTimeoutMS	Number	Controls the request timeout to fetch new environment config changes, defaults to 5 seconds, must be less than the configPollingIntervalMS value, minimum value is 1 second.
eventFlushIntervalMS	Number	Controls the interval between flushing events to the DevCycle servers, defaults to 30 seconds.
disableAutomaticEventLogging	Boolean	Disables logging of sdk generated events (e.g. aggVariableEvaluated, aggVariableDefaulted) to DevCycle.
disableCustomEventLogging	Boolean	Disables logging of custom events (from track() method) and user data to DevCycle.
flushEventQueueSize	Number	Controls the maximum size the event queue can grow to until a flush is forced. Defaults to 1000.
maxEventQueueSize	Number	Controls the maximum size the event queue can grow to until events are dropped. Defaults to 2000.
apiProxyURL	String	Allows the SDK to communicate with a proxy of DVC bucketing API / client SDK API.

User Object

The full user data must be passed into every method. The only required field is the user_id. The rest are optional and are used by the system for user segmentation into variables and features.

DVCUser Typescript Schema

const user = {
    user_id: '[email protected]',
    name: 'user 1 name',
    customData: {
        customKey: 'customValue'
    }
}
const variable = dvcClient.variable(user, 'test-feature', false)

Get and Use Variable by Key

To get values from your Variables, dvcClient.variable() is used to fetch variable values using the user data, variable key, coupled with a default value for the variable. The default variable will be used in cases where the user is not segmented into a feature using that variable, or the project configuration is unavailable to be fetched from DevCycle's CDN.

The default value can be of type string, boolean, number, or object.

DVCVariable Typescript Schema

const variable = dvcClient.variable(user, 'YOUR_VARIABLE_KEY', false)
if (variable.value) {
    // Feature Flag on
}

See getVariableByKey on the Bucketing API for the variable response format.

Getting All Variables

To grab all the segmented variables for a user:

const variables = dvcClient.allVariables(user)

See getVariables on the Bucketing API for the variable response format.

Getting All Features

You can fetch all segmented features for a user:

DVCFeature Typescript Schema

const features = dvcClient.allFeatures(user)

See getFeatures on the Bucketing API for the feature response format.

Tracking User Events

Track a custom event for a user, pass in the user and event object.

Calling Track will queue the event, which will be sent in batches to the DevCycle servers.

DVCEvent Typescript Schema

const event: DVCEvent = {
    type: 'customType',
    target: 'new_subscription',
    value: 100.1,
    date: Date.now()
}
dvcClient.track(user, event)

Flush Events

If you would like to force a flush of events in the event queue, you can call flushEvents(). Events will automatically be flushed according to the eventFlushIntervalMS option.

EdgeDB

info

EdgeDB is only available with Cloud Bucketing and does not have any impact on Local Bucketing.

EdgeDB allows you to save user data to our EdgeDB storage so that you don't have to pass in all the user data every time you identify a user. Read more about EdgeDB.

To get started, contact us at [email protected] to enable EdgeDB for your project.

Once you have EdgeDB enabled in your project, pass in the enableEdgeDB option to turn on EdgeDB mode for the SDK:

const DVC = require('@devcycle/nodejs-server-sdk')

const dvcClient = DVC.initialize('<DVC_ENVIRONMENT_SERVER_KEY>', {
  enableCloudBucketing: true,
  enableEdgeDB: true
})

const user = {
  user_id: 'test_user',
  email: '[email protected]',
  country: 'CA'
}

const variable = await dvcClient.variable(user, 'test-feature', false)

This will send a request to our EdgeDB API to save the custom data under the user test_user.

In the example, Email and Country are associated to the user test_user. In your next variable call for the same user_id, you may omit any of the data you've sent already as it will be pulled from the EdgeDB storage when segmenting to experiments and features.

Close Client

If you need to close the DVCClient object to stop all open connections and timers, call dvcClient.close(). This can be useful for cleaning DVCClient objects during unit testing.