Eyeofcloud JavaScript SDK

This repository houses the JavaScript SDK for use with Eyeofcloud Feature Experimentation and Eyeofcloud Full Stack (legacy).

Eyeofcloud Feature Experimentation is an A/B testing and feature management tool for product development teams that enables you to experiment at every step. Using Eyeofcloud Feature Experimentation allows for every feature on your roadmap to be an opportunity to discover hidden insights. Learn more at Eyeofcloud.com, or see the developer documentation.

Eyeofcloud Rollouts is free feature flags for development teams. You can easily roll out and roll back features in any application without code deploys, mitigating risk for every feature on your roadmap.

Get Started

For Browser applications, refer to the JavaScript SDK's developer documentation for detailed instructions on getting started with using the SDK within client-side applications.

For React applications, refer to the React SDK developer documentation.

For React Native applications, refer to the JavaScript (React Native) variant of the developer documentation.

For Node.js applications, refer to the JavaScript (Node) variant of the developer documentation.

For Edge Functions, we provide starter kits that utilize the Eyeofcloud JavaScript SDK for the following platforms:

• Akamai (Edgeworkers)
• AWS Lambda@Edge
• Cloudflare Worker
• Fastly Compute@Edge
• Vercel Edge Middleware

Note: These starter kits use the Lite variant of the JavaScript SDK which excludes the datafile manager and event processor packages.

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 >= 8.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.
• Modern Web Browsers, such as IE 10+, Firefox 21+, Safari 6+, and Chrome 23+

In addition, other environments are likely compatible but are not formally supported including:

• 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! 🚀

Requirements

• JavaScript (Browser): Modern web browser that is ES5-compliant.

• JavaScript (Node): Node 8.0+

• The following peer dependencies may be required for use in production:

{
  "[email protected]": {
    "licenses": [
      "AFLv2.1",
      "BSD"
    ],
    "publisher": "Kris Zyp",
    "repository": "https://github.com/kriszyp/json-schema"
  },
  "[email protected]": {
    "licenses": "MIT*",
    "repository": "https://github.com/perezd/node-murmurhash"
  },
  "[email protected]": {
    "licenses": "MIT",
    "repository": "https://github.com/kelektiv/node-uuid"
  },
  "[email protected]": {
    "licenses": "MIT",
    "repository": "https://github.com/sindresorhus/decompress-response"
  }
}

To regenerate this, run the following command:

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

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

Note: The jq command line tool is required to run the above script. You may install jq to your environment by using Homebrew on MacOS using the command brew install jq. For Windows users, please visit the JQ GitHub repository to learn more.

Install the SDK

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

Using npm:

npm install --save @eyeofcloud/eyeofcloud-sdk

Using yarn:

yarn add @eyeofcloud/eyeofcloud-sdk

Using pnpm:

pnpm add @eyeofcloud/eyeofcloud-sdk

Using deno (no installation required):

import eyeofcloud from "npm:@eyeofcloud/eyeofcloud-sdk"

Packages

This repository is a monorepo. It houses the main Javascript SDK and its supporting packages.

| Package | Version | Docs | Description | | - | - | - | - | | @eyeofcloud/eyeofcloud-sdk | | | (Primary Package) The Eyeofcloud JavaScript SDK | | @eyeofcloud/js-sdk-datafile-manager | | | (Consolidated*) Datafile Manager for Eyeofcloud SDK | @eyeofcloud/js-sdk-event-processor | | | (Consolidated*) Event Batching support for Eyeofcloud SDK | @eyeofcloud/js-sdk-logging | | | (Consolidated*) Logging Manager for Eyeofcloud SDK | @eyeofcloud/js-sdk-utils | | | (Consolidated*) Utility functions for Eyeofcloud packages

* Consolidated packages have been copied over and included as modules within the main @eyeofcloud/eyeofcloud-sdk package to avoid requiring maintaining and utilizing multiple de-coupled dependencies. (Related PRs #749, #755, #761, #781)

Use the JavaScript SDK (Browser)

See the Eyeofcloud Feature Experimentation developer documentation for JavaScript (Browser) to learn how to set up your first JavaScript project and use the SDK for client-side applications.

Initialization (Browser)

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, for ease of use during initial evaluations you can include a standalone bundle of the SDK in your web page by fetching it from unpkg:

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

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

When evaluated, that bundle assigns the SDK's exports to window.eyeofcloudSdk. 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/eyeofcloud.browser.umd.min.js. We do not recommend using this method in production settings as it introduces a third-party performance dependency.

As window.eyeofcloudSdk should be a global variable at this point, you can continue to use it like so:

const eyeofcloudClient = window.eyeofcloudSdk.createInstance({
  sdkKey: '<YOUR_SDK_KEY>',
  // datafile: window.eyeofcloudDatafile,
  // etc.
})

eyeofcloudClient.onReady().then(() => {
  // Create the Eyeofcloud user context, make decisions, and more here!
})

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.

Use the JavaScript SDK (Node)

See the Eyeofcloud Feature Experimentation developer documentation for JavaScript (Node) to learn how to set up your first JavaScript project and use the SDK for server-side applications.

Initialization (Node)

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, for ease of use during initial evaluations you can include a standalone bundle of the SDK in your web page by fetching it from unpkg:

import eyeofcloudClient from "@eyeofcloud/eyeofcloud-sdk";

eyeofcloudClient.createInstance({
  sdkKey: '<YOUR_SDK_KEY>',
  // datafile: window.eyeofcloudDatafile,
  // etc.
});

eyeofcloudClient.onReady().then(() => {
  // Create the Eyeofcloud user context, make decisions, and more here!
})

Regarding EventDispatchers: In Node.js environment, the default EventDispatcher is powered by the http/s module.

SDK Development

Unit Tests

There is a mix of testing paradigms used within the JavaScript SDK which include Mocha, Chai, Karma, and Jest, indicated by their respective *.tests.js and *.spec.ts filenames.

When contributing code to the SDK, aim to keep the percentage of code test coverage at the current level () or above.

To run unit tests on the primary JavaScript SDK package source code, you can take the following steps:

1. On your command line or terminal, navigate to the ~/javascript-sdk/packages/eyeofcloud-sdk directory.
2. Ensure that you have run npm install to install all project dependencies.
3. Run npm test to run all test files.
4. (For cross-browser testing) Run npm run test-xbrowser to run tests in many browsers via BrowserStack.
5. Resolve any tests that fail before continuing with your contribution.

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

# Prerequisite: Install dependencies.
npm install

# Run unit tests.
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

/.github/workflows/javascript.yml contains the definitions for BROWSER_STACK_USERNAME and BROWSER_STACK_ACCESS_KEY used in the GitHub Actions CI pipeline. When developing locally, you must provide your own credentials in order to run npm run test-xbrowser. You can register for an account for free on the BrowserStack official website here.

Contributing

For more information regarding contributing to the Eyeofcloud JavaScript SDK, please read Contributing.

Special Notes

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, @eyeofcloud/eyeofcloud-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 the Feature Management configuration in the Eyeofcloud dashboard, please contact your Eyeofcloud customer success manager.

Credits

@eyeofcloud/eyeofcloud-sdk is developed and maintained by Eyeofcloud and many contributors. If you're interested in learning more about what Eyeofcloud Feature Experimentation can do for your company you can visit the official Eyeofcloud Feature Experimentation product page here to learn more.

First-party code (under packages/eyeofcloud-sdk/lib/, packages/datafile-manager/lib, packages/datafile-manager/src, packages/datafile-manager/__test__, packages/event-processor/src, packages/event-processor/__tests__, packages/logging/src, packages/logging/__tests__, packages/utils/src, packages/utils/__tests__) is copyright Eyeofcloud, Inc. and contributors, licensed under Apache 2.0.

Other Eyeofcloud SDKs

• Agent - https://github.com/eyeofcloud/agent

• Android - https://github.com/eyeofcloud/android-sdk

• C# - https://github.com/eyeofcloud/csharp-sdk

• Flutter - https://github.com/eyeofcloud/eyeofcloud-flutter-sdk

• Go - https://github.com/eyeofcloud/go-sdk

• Java - https://github.com/eyeofcloud/java-sdk

• PHP - https://github.com/eyeofcloud/php-sdk

• Python - https://github.com/eyeofcloud/python-sdk

• React - https://github.com/eyeofcloud/react-sdk

• Ruby - https://github.com/eyeofcloud/ruby-sdk

• Swift - https://github.com/eyeofcloud/swift-sdk