Node.js SDK Usage

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.

DevCycleUser Typescript Schema

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

const user: DevCycleUser = {
  user_id: 'user1@devcycle.com',
  name: 'user 1 name',
  customData: {
    customKey: 'customValue',
  },
}
const variable = devcycleClient.variable(user, 'test-feature', false)

In addition to the properties you set on the DevCycleUser yourself, these properties are automatically set by the SDK and are ready for segmentation:

Property	Type	Description
platform	String	Platform/OS
platformVersion	String	Platform/OS Version

Get and Use Variable by Key

To get values from your Variables, devcycleClient.variableValue() 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.

const value = devcycleClient.variableValue(user, '<YOUR_VARIABLE_KEY>', false)
if (value) {
  // Feature Flag on
}

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

If you would like to get the full Variable object defined by DVCVariable Typescript Schema you can use devcycleClient.variable() instead. This contains fields such as: key, value, type, defaultValue, isDefaulted, eval: evaluation object containing reason, details, and targetId for why the Variable was bucketed into its value (see Evaluation Reasons).

Getting All Variables

To grab all the segmented Variables for a user:

const variables = devcycleClient.allVariables(user)

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

caution

This method is intended to be used for debugging and analytics purposes, not as a method for retrieving the value of Variables to change code behaviour. For that purpose, we strongly recommend using the individual Variable access method described in Get and use Variable by key Using this method instead will result in no evaluation events being tracked for individual Variables, and will not allow the use of other DevCycle features such as Code Usage detection

Getting All Features

You can fetch all segmented Features for a user:

DVCFeature Typescript Schema

const features = devcycleClient.allFeatures(user)

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

Track 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.

DevCycleEvent Typescript Schema

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

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

Set Client Custom Data

To assist with segmentation and bucketing you can set a custom data map that will be used for all Variable and Feature evaluations. User specific customData or privateCustomData will override client custom data.

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

const customData: DVCCustomDataJSON = {
  'some-key': 'some-value',
}

devcycleClient.setClientCustomData(customData)

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 support@devcycle.com 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:

import { initializeDevCycle, DevCycleUser } from '@devcycle/nodejs-server-sdk'

const devcycleClient = initializeDevCycle('<DEVCYCLE_SERVER_SDK_KEY>', {
  enableCloudBucketing: true,
  enableEdgeDB: true,
})

const user: DevCycleUser = {
  user_id: 'test_user',
  email: 'example@example.ca',
  country: 'CA',
}

const variable = await devcycleClient.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.

Realtime Updates

This feature reduces the number of polling requests that are made to the DevCycle Config CDN, and instead will use a long-lived HTTP connection (Server Sent Events) to receive updates when there is a new config available. This reduces outbound network traffic, as well as optimizes the SDK for efficiency.

To disable realtime updates, pass in the disableRealtimeUpdates option to the SDK initialization:

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

const devcycleClient = initializeDevCycle('<DEVCYCLE_SERVER_SDK_KEY>', {
  disableRealtimeUpdates: true,
})

Evaluation Hooks

Using evaluation hooks, you can hook into the lifecycle of a Variable evaluation to execute code before and after execution of the evaluation.

Note: Each evaluation will wait for all hooks before returning the Variable evaluation, which depending on the complexity of the hooks will cause slower function call times. This also may lead to blocking Variable evaluations in the future until all hooks return depending on the volume of calls to .variable.

warning

Do not call any Variable evaluation functions (.variable/.variableValue) in any of the hooks, as it may cause infinite recursion.

To add a hook:

const client = new DevCycleClient('token')
client.addHook(
  new EvalHook(
    (context) => {
      // before hook
    },
    (context, variableDetails) => {
      // after hook
    },
    (context, variableDetails) => {
      // onFinally hook
    },
    (context, variableDetails) => {
      // error hook
    },
  ),
)

You can also clear the hooks:

const client = new DevCycleClient('token')
client.clearHooks()

Close Client

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