Skip to main content

OpenFeature Provider

OpenFeature is an open standard that provides a vendor-agnostic, community-driven API for feature flagging that works with DevCycle.

DevCycle provides a NodeJS implementation of the OpenFeature Provider interface directly from the SDK using the getOpenFeatureProvider() method.

Usage​

Installation​

Install the DevCycle NodeJS Server SDK and the OpenFeature Server SDK peer dependencies:

NPM​

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

Yarn​

yarn add @devcycle/nodejs-server-sdk @openfeature/server-sdk @openfeature/core

Getting Started​

Initialize the DevCycle SDK and set the DevCycleProvider as the provider for OpenFeature:

import { OpenFeature, Client } from '@openfeature/server-sdk'
import { initializeDevCycle } from '@devcycle/nodejs-server-sdk'

const { DEVCYCLE_SERVER_SDK_KEY } = process.env
...

// Initialize the DevCycle SDK
const devcycleClient = initializeDevCycle(DEVCYCLE_SERVER_SDK_KEY)
// Set the provider for OpenFeature from the DevCycleClient
await OpenFeature.setProviderAndWait(await devcycleClient.getOpenFeatureProvider())
// Create the OpenFeature client
openFeatureClient = OpenFeature.getClient()

Evaluate a Variable​

Use a Variable value by creating the EvaluationContext, then passing the Variable key, default value, and EvaluationContext to one of the OpenFeature flag evaluation methods.

// Set the context for the OpenFeature client, you can use 'targetingKey' or 'user_id'
const context = { targetingKey: 'node_sdk_test' }

// Retrieve a boolean flag from the OpenFeature client
const boolFlag = await openFeatureClient.getBooleanValue('boolean-flag', false, context)

Tracking Events​

You can use the OpenFeature track method to track events which will be sent to DevCycle as custom events. Calling track will queue the event, which will be sent in batches to the DevCycle servers.

const context = { targetingKey: 'node_sdk_test' }
openFeatureClient.track('custom-event', context, {
  target: 'event-target',
  value: 100,
  metaDataField: 'value',
})

To track custom events with OpenFeature you are required to set the first argument as the event name, and pass the EvaluationContext as the second argument. The event name will be used as the event's type in DevCycle, and you can optionally set a value / target / date as defined in the DevCycleEvent Typescript Schema. Any additional properties will be added to the event as metaData fields.

Passing DevCycleOptions to the DevCycleProvider​

Ensure that you pass any custom DevCycleOptions set on the DevCycleClient instance to the DevCycleProvider constructor

const options = { logger: dvcDefaultLogger({ level: 'debug' }) }
const devcycleClient = initializeDevCycle(DEVCYCLE_SERVER_SDK_KEY, options)
await OpenFeature.setProviderAndWait(
  await devcycleClient.getOpenFeatureProvider(),
)

Required TargetingKey​

For DevCycle SDK to work we require either a targetingKey or user_id to be set on the OpenFeature context. This is used to identify the user as the user_id for a DevCycleUser in DevCycle.

Context properties to DevCycleUser​

The provider will automatically translate known DevCycleUser properties from the OpenFeature context to the DevCycleUser object. DevCycleUser TypeScript Interface

For example all these properties will be set on the DevCycleUser:

openFeatureClient.setContext({
  user_id: 'user_id',
  email: '[email protected]',
  name: 'name',
  language: 'en',
  country: 'CA',
  appVersion: '1.0.11',
  appBuild: 1000,
  customData: { custom: 'data' },
  privateCustomData: { private: 'data' },
})

Context properties that are not known DevCycleUser properties will be automatically added to the customData property of the DevCycleUser.

Context Limitations​

DevCycle only supports flat JSON Object properties used in the Context. Non-flat properties will be ignored.

For example obj will be ignored:

openFeatureClient.setContext({
  user_id: 'user_id',
  obj: { key: 'value' },
})

JSON Flag Limitations​

The OpenFeature spec for JSON flags allows for any type of valid JSON value to be set as the flag value.

For example the following are all valid default value types to use with OpenFeature:

// Invalid JSON values for the DevCycle SDK, will return defaults
openFeatureClient.getObjectValue('json-flag', ['arry'])
openFeatureClient.getObjectValue('json-flag', 610)
openFeatureClient.getObjectValue('json-flag', false)
openFeatureClient.getObjectValue('json-flag', 'string')
openFeatureClient.getObjectValue('json-flag', null)

However, these are not valid types for the DevCycle SDK, the DevCycle SDK only supports JSON Objects:

// Valid JSON Object as the default value, will be evaluated by the DevCycle SDK
openFeatureClient.getObjectValue('json-flag', { default: 'value' })