|
1 | | -# Fullstack Labs |
| 1 | +# JS SDK Wrapper |
2 | 2 |
|
3 | | -## Installation |
| 3 | +# What is it |
4 | 4 |
|
5 | | -This repo uses Lerna, to install all depedencies run: |
| 5 | +- A backwards compatible wrapper around the JavascriptSDK |
| 6 | +- Provides extendible datafile loading and caching strategies |
| 7 | +- Handles async loading of userId and UserAttributes |
| 8 | +- Provides mechanisms to block rendering / execution until Optimizely is loaeded with a fallback timeout |
| 9 | +- All new features are opt-in, can be used exactly the same way as JavascriptSDK if desired |
6 | 10 |
|
| 11 | + |
| 12 | +# Datafile loading / management |
| 13 | + |
| 14 | +## Load datafile already on the page |
| 15 | + |
| 16 | +This is the ideal case and prevents a lot of timing issues and complexity, however we realize not all customers will have the ability to this. |
| 17 | + |
| 18 | +```js |
| 19 | +import { Optimizely } from '@optimizely/js-web-sdk' |
| 20 | +const optimizely = new Optimizely({ |
| 21 | + datafile: window.datafile, |
| 22 | +}) |
| 23 | +// all calls can happen immediately after (sync) |
| 24 | +optimizely.activate('my-exp', 'user1') |
7 | 25 | ``` |
8 | | -lerna bootstrap |
| 26 | + |
| 27 | +## Load datafile by URL |
| 28 | + |
| 29 | +This is not an optimal solution as it requires us to think about timing and ensure that we only call `optimizely` functions after the datafile is loaded or ensure we handle the case where `optimizely` is not ready and we need to delay loading or display a default. |
| 30 | + |
| 31 | +_Asnyc load and wait until datafile is loaded_ |
| 32 | + |
| 33 | +```js |
| 34 | +import { Optimizely } from '@optimizely/js-web-sdk' |
| 35 | + |
| 36 | +const optimizely = new Optimizely({ |
| 37 | + SDKKey: 'GaXr9RoDhRcqXJm3ruskRa', |
| 38 | +}) |
| 39 | +await optimizely.onReady() |
| 40 | +// datafile is gauranteed to be loaded |
| 41 | +initApp() |
9 | 42 | ``` |
10 | 43 |
|
11 | | -To run an individual project |
| 44 | +The above example may not be great, perhaps you want a gaurantee that the page wont block longer than X milliseconds. |
| 45 | + |
| 46 | +_Asnyc load and wait up til 100ms_ |
| 47 | + |
| 48 | +```js |
| 49 | +import { Optimizely } from '@optimizely/js-web-sdk' |
12 | 50 |
|
| 51 | +const optimizely = new Optimizely({ |
| 52 | + SDKKey: 'GaXr9RoDhRcqXJm3ruskRa', |
| 53 | +}) |
| 54 | +// dont block for more than 100sec |
| 55 | +await optimizely.onReady({ timeout: 100 }) |
| 56 | +// at this point datafile may or may not be loaded |
| 57 | +// however calls to track will be queued when the datafile is ready |
| 58 | +initApp() |
| 59 | + |
| 60 | +// additionally in other places you can hook into onReady without a timeout |
| 61 | +// to gaurantee optimizely is loaded |
| 62 | +optimizely.onReady().then(() => { |
| 63 | + // optimizely is gauranteed to be loaded at this point |
| 64 | +}) |
13 | 65 | ``` |
14 | | -cd packages/PACKAGE_NAME |
| 66 | + |
| 67 | +### Second page load |
| 68 | + |
| 69 | +By default loading the datafile by URL will store the contents of the datafile in `localStorage`, on second page load we are guaranteed to have synchronous access to the datafile. |
| 70 | + |
| 71 | +The underlying DatafileManager will also make a background request to get an updated datafile, however that will not be registered until the next instantiation of `Optimizely` which is usually the next page load. |
| 72 | + |
| 73 | +_When using optimizely async the user will only have to pay the loading cost once on first page load, subsequent page loads are always synchronous_ |
| 74 | + |
| 75 | +### Using React |
| 76 | + |
| 77 | +```js |
| 78 | +// ./optimizely.js |
| 79 | +import optimizelySDK from '@optimizely/js-web-sdk' |
| 80 | + |
| 81 | +const optimizely = optimizelySDK.createInstance({ |
| 82 | + SDKKey: 'GaXr9RoDhRcqXJm3ruskRa', |
| 83 | + userId: window.userId, |
| 84 | +}) |
| 85 | + |
| 86 | +export { optimizely } |
15 | 87 | ``` |
16 | 88 |
|
17 | | -and lookup what available commands in in the `package.json` scripts field |
| 89 | +```jsx |
| 90 | +// ./App.jsx |
| 91 | +import React, { Component } from 'react' |
| 92 | +import { optimizely } from './optimizely' |
| 93 | +import { |
| 94 | + OptimizelyProvider, |
| 95 | + OptimizelyExperiment, |
| 96 | +} from '@optimizely/react-sdk' |
| 97 | + |
| 98 | +class App extends Component { |
| 99 | + render() { |
| 100 | + <OptimizelyProvider optimizely={optimizely} timeout={50}> |
| 101 | + <OptimizelyExperiment experiment="header-test"> |
| 102 | + {variation => |
| 103 | + variation === 'detailed' ? <DetailedHeader /> : <SimpleHeader /> |
| 104 | + } |
| 105 | + </OptimizelyExperiment> |
| 106 | + </OptimizelyProvider> |
| 107 | + } |
| 108 | +} |
| 109 | +``` |
18 | 110 |
|
19 | | -## Packages |
| 111 | +In the above example, setting `timeout={50}` will allow any Optimizely components to wait up to 50ms for the datafile to load. |
20 | 112 |
|
21 | | -### JS Web SDK Wrapper |
| 113 | +_Benefits to the React approach_ |
| 114 | +In the case where the datafile is already loaded, either from being on the page already or cached in local storage this approach doesn’t have a flash or a loading spinner. |
22 | 115 |
|
23 | | -[JS Web SDK README](packages/js-web-sdk/) |
| 116 | +On first page load, if the datafile is slow (due to slow connection) it will render the fallback. |
24 | 117 |
|
25 | | -An OptimizelySDK wrapper targeted for browsers |
| 118 | +# User management |
26 | 119 |
|
27 | | -### React SDK |
| 120 | +## Storing userId and attributes on instance |
28 | 121 |
|
29 | | -[React SDK README](packages/react-sdk/) |
| 122 | +This SDK supports remembering userId and attributes by passing them to instantiation |
30 | 123 |
|
31 | | -A collection of components to more easily implement fullstack AB Tests, Feature Test and Feature Variables |
| 124 | +```js |
| 125 | +import { Optimizely } from '@optimizely/js-web-sdk' |
| 126 | +const optimizely = new Optimizely({ |
| 127 | + datafile: window.datafile, |
| 128 | + userId: window.userId |
| 129 | + attibutes: { |
| 130 | + plan_type: 'silver' |
| 131 | + } |
| 132 | +}) |
| 133 | +// no need to pass userId or attributes |
| 134 | +optimizely.activate('my-exp') |
32 | 135 |
|
33 | | -An OptimizelySDK wrapper targeted for browsers, maintains state of user and attributes as well as supplying a simpler API. |
| 136 | +// you can always override on a per call basis |
| 137 | +optimizely.activate('my-exp', 'otheruser', { |
| 138 | + plan_type: 'gold', |
| 139 | +}) |
34 | 140 |
|
35 | | -### React Example (TypeScript) |
| 141 | +// However this isn't recommeneded as "track" calls also need to match this |
| 142 | +// TODO: does easy event tracking fix this? |
| 143 | +``` |
| 144 | + |
| 145 | +## Generating a random user Id and storing in cookie |
| 146 | + |
| 147 | +The following code will generate a random userId if the user doesnt already have one saved in a cookie. |
36 | 148 |
|
37 | | -[React Example TypeScript README](packages/react-example-ts/) |
| 149 | +```js |
| 150 | +import { |
| 151 | + Optimizely, |
| 152 | + CookieRandomUserIdLoader, |
| 153 | +} from '@optimizely/js-web-sdk' |
38 | 154 |
|
39 | | -### React Example (React v15) |
| 155 | +const optimizely = new Optimizely({ |
| 156 | + datafile: window.datafile, |
| 157 | + userIdLoader: new CookieRandomUserIdLoader(), |
| 158 | + attibutes: { |
| 159 | + plan_type: 'silver' |
| 160 | + } |
| 161 | +}) |
| 162 | +``` |
| 163 | + |
| 164 | +## Not managing User IDs |
40 | 165 |
|
41 | | -[React Example (React v15) README](packages/react-example-15/) |
| 166 | +Of course this is totally opt in, you can continue to pass userId into all api calls, the same as the Node Javascript SDK |
42 | 167 |
|
43 | | -### React Example (React v16) |
| 168 | +```js |
| 169 | +import { Optimizely } from '@optimizely/js-web-sdk' |
44 | 170 |
|
45 | | -[React Example (React v16) README](packages/react-example-16/) |
| 171 | +const optimizely = new Optimizely({ |
| 172 | + datafile: window.datafile, |
| 173 | +}) |
| 174 | +optimizely.activate('exp1', 'user1') |
| 175 | +``` |
0 commit comments