|
1 | | -# Optimizely JavaScript SDK |
| 1 | +# JavaScript SDK for Optimizely X Full Stack |
| 2 | +[](https://www.npmjs.com/package/@optimizely/optimizely-sdk) |
| 3 | +[](https://www.npmjs.com/package/@optimizely/optimizely-sdk) |
| 4 | +[](https://travis-ci.org/optimizely/javascript-sdk) |
| 5 | +[](https://coveralls.io/github/optimizely/javascript-sdk) |
| 6 | +[](https://choosealicense.com/licenses/apache-2.0/) |
2 | 7 |
|
3 | | -This repository houses the JavaScript SDK for Optimizely X Full Stack. |
| 8 | + |
| 9 | +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](https://www.optimizely.com/products/full-stack/), or see the [documentation](https://developers.optimizely.com/x/solutions/sdks/reference/index.html?language=node). |
| 10 | + |
| 11 | +This directory contains the source code for the JavaScript SDK, which is usable in Node.js, browsers, and beyond. |
4 | 12 |
|
5 | 13 | ## Getting Started |
6 | 14 |
|
7 | | -### Installing the SDK |
| 15 | +### Prerequisites |
| 16 | + |
| 17 | +Ensure the SDK supports all of the platforms you're targeting. In particular, the SDK targets any ES5-compliant JavaScript environment. We officially support: |
| 18 | + - 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. |
| 19 | + - [Web browsers](https://caniuse.com/#feat=es5) |
| 20 | + |
| 21 | +Other environments likely are compatible, too, but note that we don't officially support them: |
| 22 | + - Progressive Web Apps, WebViews, and hybrid mobile apps like those built with React Native and Apache Cordova. |
| 23 | + - [Cloudflare Workers](https://developers.cloudflare.com/workers/) and [Fly](https://fly.io/), both of which are powered by recent releases of V8. |
| 24 | + - Anywhere else you can think of that might embed a JavaScript engine. The sky is the limit; experiment everywhere! 🚀 |
8 | 25 |
|
9 | | -The SDK is available through [npm](https://npmjs.com/package/optimizely-sdk). To install: |
| 26 | +Once you've validated that the SDK supports the platforms you're targeting, fetch the package from [NPM](https://www.npmjs.com/package/@optimizely/optimizely-sdk). Using `npm`: |
10 | 27 |
|
11 | 28 | ``` |
12 | | -npm install @optimizely/optimizely-sdk --save |
| 29 | +npm install --save @optimizely/optimizely-sdk |
13 | 30 | ``` |
14 | 31 |
|
15 | | -Or to use in a non CommonJS fashion in the Browser: |
| 32 | +### Usage |
| 33 | +See the Optimizely X Full Stack [developer documentation](http://developers.optimizely.com/server/reference/index.html) to learn how to set up your first JavaScript project and use the SDK. |
16 | 34 |
|
17 | | -1. Run `npm run build` |
18 | | -2. Pull in `dist/optimizely.browser.umd.min.js` as a `<script>` |
19 | | -3. Use as global variable `window.optimizelyClient` |
| 35 | +Regarding `EventDispatcher`s: In Node.js and browser environments, the default `EventDispatcher` is powered by the [`http/s`](https://nodejs.org/api/http.html) modules and by [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest#Browser_compatibility), respectively. In all other environments, you must supply your own `EventDispatcher`. |
20 | 36 |
|
21 | 37 | ### Migrating from 1.x.x |
22 | 38 |
|
23 | 39 | This version represents a major version change and, as such, introduces some breaking changes: |
24 | 40 |
|
25 | | -- The Node SDK is now combined with the JavaScript SDK so that we have one `optimizely-sdk` package that works across both server + browser environments. |
| 41 | +- 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. |
26 | 42 |
|
27 | | -- We no longer support legacy Node versions (under 4.0). |
| 43 | +- We no longer support Node.js < 4.0.0, which collectively [reached end-of-life](https://github.com/nodejs/Release#end-of-life-releases) on 2016-12-31. |
28 | 44 |
|
29 | 45 | - 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`](https://developers.optimizely.com/x/solutions/sdks/reference/index.html?language=javascript#event-tags). |
30 | 46 |
|
31 | | -### Feature Management Access |
32 | | - |
33 | | -To access the Feature Management configuration in the Optimizely dashboard, please contact your Optimizely account executive. |
34 | | - |
35 | | -### Using the SDK |
36 | | -See the Optimizely X Full Stack testing [developer documentation](http://developers.optimizely.com/server/reference/index.html) to learn how to set up your first JavaScript project and use the SDK. |
37 | | - |
38 | | -## Development |
| 47 | +### Feature Management access |
39 | 48 |
|
40 | | -### Installing dependencies |
| 49 | +To access Feature Management in the Optimizely web application, please contact your Optimizely account executive. |
41 | 50 |
|
42 | | -```npm install``` |
| 51 | +## Contributing |
| 52 | +This information is relevant only if you plan on contributing to the SDK itself. |
43 | 53 |
|
44 | | -### Unit tests |
| 54 | +```sh |
| 55 | +# Prerequisite: Install dependencies. |
| 56 | +npm install |
45 | 57 |
|
46 | | -You can run all unit tests with: |
47 | | -``` |
| 58 | +# Run unit tests with mocha. |
48 | 59 | npm test |
49 | | -``` |
50 | 60 |
|
51 | | -### Build distribution packages |
52 | | - |
53 | | -``` |
54 | | -npm run build |
| 61 | +# Run unit tests in many browsers, currently via BrowserStack. |
| 62 | +# For this to work, the following environment variables must be set: |
| 63 | +# - BROWSER_STACK_USERNAME |
| 64 | +# - BROWSER_STACK_PASSWORD |
| 65 | +npm run test-xbrowser |
55 | 66 | ``` |
56 | 67 |
|
57 | | -This command will build several distribution bundles under the `dist` directory: |
58 | | -1. optimizely.browser.cjs.js - This is the main entry point for browser/client-side bundles |
59 | | -2. optimizely.browser.umd.js - This is used when not packaging the optimizely-sdk with your own JS bundles. Instead you would load this script as a `<script>` tag and reference it via the global var `optimizelyClient` |
60 | | -3. optimizely.node.js - This is the main entry point for Node apps |
61 | | - |
62 | | -The browser bundles also come with a minified / production-ready version. |
63 | | - |
64 | | -### Environment Variables |
65 | | - |
66 | | -The .yml of this project contains environment vairables for ```BROWSER_STACK_USERNAME``` and ```BROWSER_STACK_ACCESS_KEY```. |
| 68 | +[.travis.yml](/.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](https://docs.travis-ci.com/user/environment-variables/#Defining-encrypted-variables-in-.travis.yml). |
67 | 69 |
|
68 | | -These variables, created in BrowserStack, are encrypted by the Travis CI public key. This is done directly with the Travis CI command line tools; for additional information see travis encrypt-file. |
|
0 commit comments