@optimizely/optimizely-sdk

What is @optimizely/optimizely-sdk?

@optimizely/optimizely-sdk is a feature flagging and A/B testing library that allows developers to experiment with and optimize their applications. It provides tools for running experiments, managing feature flags, and personalizing user experiences.

What are @optimizely/optimizely-sdk's main functionalities?

Feature Flagging

This feature allows you to manage feature flags, enabling or disabling features for specific users or groups of users.

const optimizely = require('@optimizely/optimizely-sdk');
const optimizelyClient = optimizely.createInstance({
  sdkKey: 'your-sdk-key'
});

const userId = 'user123';
const featureEnabled = optimizelyClient.isFeatureEnabled('new_feature', userId);

if (featureEnabled) {
  console.log('Feature is enabled for this user');
} else {
  console.log('Feature is not enabled for this user');
}

A/B Testing

This feature allows you to run A/B tests by assigning users to different variations of an experiment and measuring their behavior.

const optimizely = require('@optimizely/optimizely-sdk');
const optimizelyClient = optimizely.createInstance({
  sdkKey: 'your-sdk-key'
});

const userId = 'user123';
const variation = optimizelyClient.activate('experiment_key', userId);

if (variation === 'variation_1') {
  console.log('User is in variation 1');
} else if (variation === 'variation_2') {
  console.log('User is in variation 2');
} else {
  console.log('User is in control group');
}

Event Tracking

This feature allows you to track events and user actions, which can be used to measure the impact of experiments and feature flags.

const optimizely = require('@optimizely/optimizely-sdk');
const optimizelyClient = optimizely.createInstance({
  sdkKey: 'your-sdk-key'
});

const userId = 'user123';
optimizelyClient.track('event_key', userId, { revenue: 100 });
console.log('Event tracked for user');

Other packages similar to @optimizely/optimizely-sdk

launchdarkly-node-server-sdk

LaunchDarkly is a feature management platform that provides similar functionality to Optimizely, including feature flagging, A/B testing, and user segmentation. It is known for its robust feature set and ease of use.

unleash-client

Unleash is an open-source feature management solution that offers feature toggling and gradual rollouts. It is a good alternative for those looking for a self-hosted solution with a strong community support.

splitio

Split.io is a feature experimentation platform that provides feature flagging, A/B testing, and real-time analytics. It is designed for teams looking to make data-driven decisions and optimize their applications.

README

JavaScript SDK for Optimizely X Full Stack

Optimizely X Full Stack is A/B testing and feature management for product development teams. Experiment in any application. Make every feature on your roadmap an opportunity to learn. Learn more at the landing page, or see the documentation.

This directory contains the source code for the JavaScript SDK, which is usable in Node.js, browsers, and beyond.

Getting Started

Prerequisites

Ensure the SDK supports all of the platforms you're targeting. In particular, the SDK targets any ES5-compliant JavaScript environment. We officially support:

• Node.js >= 4.0.0. By extension, environments like AWS Lambda, Google Cloud Functions, and Auth0 Webtasks are supported as well. Older Node.js releases likely work too (try npm test to validate for yourself), but are not formally supported.
• Web browsers

Other environments likely are compatible, too, but note that we don't officially support them:

• Progressive Web Apps, WebViews, and hybrid mobile apps like those built with React Native and Apache Cordova.
• Cloudflare Workers and Fly, both of which are powered by recent releases of V8.
• Anywhere else you can think of that might embed a JavaScript engine. The sky is the limit; experiment everywhere! 🚀

Once you've validated that the SDK supports the platforms you're targeting, fetch the package from NPM. Using npm:

npm install --save @optimizely/optimizely-sdk

Usage

See the Optimizely X Full Stack developer documentation to learn how to set up your first JavaScript project and use the SDK.

The package's entry point is a CommonJS module, which can be used directly in environments which support it (e.g., Node.js, or loaded in a browser via Browserify or RequireJS). Additionally, you can include a standalone bundle of the SDK in your web page by fetching it from unpkg:

<script src="https://unpkg.com/@optimizely/optimizely-sdk/dist/optimizely.browser.umd.min.js"></script>

<!-- You can also use the unminified version if necessary -->
<script src="https://unpkg.com/@optimizely/optimizely-sdk/dist/optimizely.browser.umd.js"></script>

When evaluated, that bundle assigns the SDK's exports to window.optimizelySdk. If you wish to use the asset locally (for example, if unpkg is down), you can find it in your local copy of the package at dist/optimizely.browser.umd.min.js.

Regarding EventDispatchers: In Node.js and browser environments, the default EventDispatcher is powered by the http/s modules and by XMLHttpRequest, respectively. In all other environments, you must supply your own EventDispatcher.

Migrating from 1.x.x

This version represents a major version change and, as such, introduces some breaking changes:

• The Node.js SDK is now combined with the JavaScript SDK. We now have just one package, @optimizely/optimizely-sdk, that works in many JavaScript environments.

• We no longer support Node.js < 4.0.0, which collectively reached end-of-life on 2016-12-31.

• You will no longer be able to pass in revenue value as a stand-alone argument to the track call. Instead you will need to pass it as an entry in the eventTags.

Feature Management access

To access Feature Management in the Optimizely web application, please contact your Optimizely account executive.

Contributing

This information is relevant only if you plan on contributing to the SDK itself.

# Prerequisite: Install dependencies.
npm install

# Run unit tests with mocha.
npm test

# Run unit tests in many browsers, currently via BrowserStack.
# For this to work, the following environment variables must be set:
#   - BROWSER_STACK_USERNAME
#   - BROWSER_STACK_PASSWORD
npm run test-xbrowser

.travis.yml contains the definitions for BROWSER_STACK_USERNAME and BROWSER_STACK_ACCESS_KEY used in CI. These values are Optimizely's BrowserStack credentials, encrypted with our Travis CI public key. These creds can be rotated by following these docs.

Credits

First-party code (under lib/) is copyright Optimizely, Inc. and contributors, licensed under Apache 2.0.

Additional Code

Prod dependencies are as follows:

{
  "json-schema@0.2.3": {
    "licenses": [
      "AFLv2.1",
      "BSD"
    ],
    "publisher": "Kris Zyp",
    "repository": "https://github.com/kriszyp/json-schema"
  },
  "lodash@4.17.10": {
    "licenses": "MIT",
    "publisher": "John-David Dalton",
    "repository": "https://github.com/lodash/lodash"
  },
  "murmurhash@0.0.2": {
    "licenses": "MIT*",
    "repository": "https://github.com/perezd/node-murmurhash"
  },
  "sprintf@0.1.5": {
    "licenses": "BSD-3-Clause",
    "publisher": "Moritz Peters",
    "repository": "https://github.com/maritz/node-sprintf"
  },
  "uuid@3.2.1": {
    "licenses": "MIT",
    "repository": "https://github.com/kelektiv/node-uuid"
  }
}

To regenerate this, run the following command:

npx license-checker --production --json | jq 'map_values({ licenses, publisher, repository }) | del(.[][] | nulls)'

and remove the self (@optimizely/optimizely-sdk) entry.

Changelog

[3.2.0-alpha] - April 26nd, 2019

New Features

• Added support for automatic datafile management
  • To use automatic datafile management, include sdkKey as a string property in the options object you pass to createInstance.
  • When sdkKey is provided, the SDK instance will download the datafile associated with that sdkKey immediately upon construction. When the download completes, the SDK instance will update itself to use the downloaded datafile.
  • Use the onReady method to wait until the download is complete and the SDK is ready to use.
  • Customize datafile management behavior by passing a datafileOptions object within the options you pass to createInstance.
    • Enable automatic updates by passing autoUpdate: true. Periodically (on the provided update interval), the SDK instance will download the datafile and update itself. Use this to ensure that the SDK instance is using a fresh datafile reflecting changes recently made to your experiment or feature configuration.
  • Add a notification listener for the OPTIMIZELY_CONFIG_UPDATE notification type to be notified when an instance updates its Optimizely config after obtaining a new datafile.
  • Stop active downloads and cancel pending downloads by calling the close method

Create an instance with datafile management enabled

const optimizely = require('@optimizely/optimizely-sdk');
const optimizelyClientInstance = optimizely.createInstance({
  sdkKey: '12345', // Provide the sdkKey of your desired environment here
});

Use onReady to wait until optimizelyClientInstance has a datafile

const optimizely = require('@optimizely/optimizely-sdk');
const optimizelyClientInstance = optimizely.createInstance({
  sdkKey: '12345',
});
optimizelyClientInstance.onReady().then(() => {
  // optimizelyClientInstance is ready to use, with datafile downloaded from the Optimizely CDN
});

Enable automatic updates, add notification listener for OPTIMIZELY_CONFIG_UPDATE notification type, and stop automatic updates

const optimizely = require('@optimizely/optimizely-sdk');
const optimizelyClientInstance = optimizely.createInstance({
  sdkKey: '12345',
  datafileOptions: {
    autoUpdate: true,
    updateInterval: 600000, // 10 minutes in milliseconds
  },
});
optimizelyClientInstance.notificationCenter.addNotificationListener(
  optimizely.enums.NOTIFICATION_TYPES.OPTIMIZELY_CONFIG_UPDATE,
  () => {
    // optimizelyClientInstance has updated its Optimizely config
  }
);
// Stop automatic updates - optimizelyClientInstance will use whatever datafile it currently has from now on
optimizelyClientInstance.close();

Changed

• Forced variation logic has been moved from the project config module to the decision service. Prefixes for forced-variation-related log messages will reflect this change.