diff --git a/README.md b/README.md index b54c585..9455668 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,14 @@ # Unleash Proxy Client for the browser (JS) -The JavaScript proxy client is a tiny Unleash client written in JavaScript without any external dependencies (except from browser APIs). This client stores toggles relevant for the current user in `localStorage` and synchronizes with Unleash (the [Unleash front-end API](https://docs.getunleash.io/reference/front-end-api) _or_ the [Unleash proxy](https://docs.getunleash.io/reference/unleash-proxy)) in the background. Because toggles are stored in the user's browser, the client can use them to bootstrap itself the next time the user visits the same web page. +The JavaScript client is a tiny Unleash client written in JavaScript without any external dependencies (except from browser APIs). This client stores toggles relevant for the current user in `localStorage` and synchronizes with Unleash (the [Unleash front-end API](https://docs.getunleash.io/reference/front-end-api) _or_ [Unleash edge](https://docs.getunleash.io/reference/unleash-edge)) in the background. Because toggles are stored in the user's browser, the client can use them to bootstrap itself the next time the user visits the same web page. -This client expect `fetch` to be available. If you need to support older -browsers you should probably use the [fetch polyfill](https://github.com/github/fetch). +This client expect `fetch` to be available. ## Frameworks supported This package is not tied to any framework, but can be used together most popular frameworks, examples: -- [Unleash React SDK](https://docs.getunleash.io/sdks/proxy-react) +- [Unleash React SDK](https://docs.getunleash.io/reference/sdks/react) - [React](https://reactjs.org/) - [React Native](https://reactnative.dev/) - [Angular JS](https://angularjs.org/) @@ -28,7 +27,7 @@ npm install unleash-proxy-client --- -💡 **TIP**: As a client-side SDK, this SDK requires you to connect to either an Unleash proxy or to the Unleash front-end API. Refer to the [connection options section](#connection-options) for more information. +💡 **TIP**: As a client-side SDK, this SDK requires you to connect to either Unleash Edge or to the Unleash front-end API. Refer to the [connection options section](#connection-options) for more information. --- @@ -51,7 +50,7 @@ unleash.start(); To connect this SDK to your Unleash instance's [front-end API](https://docs.getunleash.io/reference/front-end-api), use the URL to your Unleash instance's front-end API (`/api/frontend`) as the `url` parameter. For the `clientKey` parameter, use a `FRONTEND` token generated from your Unleash instance. Refer to the [_how to create API tokens_](https://docs.getunleash.io/how-to/how-to-create-api-tokens) guide for the necessary steps. -To connect this SDK to the [Unleash proxy](https://docs.getunleash.io/reference/unleash-proxy), use the proxy's URL and a [proxy client key](https://docs.getunleash.io/reference/api-tokens-and-client-keys#proxy-client-keys). The [_configuration_ section of the Unleash proxy docs](https://docs.getunleash.io/reference/unleash-proxy#configuration) contains more info on how to configure client keys for your proxy. +This SDK can also be used with [Unleash Edge](https://docs.getunleash.io/reference/unleash-edge). ### Step 3: Let the client synchronize @@ -59,10 +58,10 @@ You should wait for the client's `ready` or `initialized` events before you star ```js unleash.on('ready', () => { - if (unleash.isEnabled('proxy.demo')) { - console.log('proxy.demo is enabled'); + if (unleash.isEnabled('js.demo')) { + console.log('js.demo is enabled'); } else { - console.log('proxy.demo is disabled'); + console.log('js.demo is disabled'); } }); ``` @@ -74,7 +73,7 @@ The difference between the events is described in the [section on available even Once the client is ready, you can start checking features in your application. Use the `isEnabled` method to check the state of any feature you want: ```js -unleash.isEnabled('proxy.demo'); +unleash.isEnabled('js.demo'); ``` You can use the `getVariant` method to get the variant of an **enabled feature that has variants**. If the feature is disabled or if it has no variants, then you will get back the [**disabled variant**](https://docs.getunleash.io/reference/feature-toggle-variants#the-disabled-variant) @@ -117,13 +116,13 @@ The Unleash SDK takes the following options: | option | required | default | description | |-------------------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------| -| url | yes | n/a | The Unleash Proxy URL to connect to. E.g.: `https://examples.com/proxy` | -| clientKey | yes | n/a | The Unleash Proxy Secret to be used | -| appName | yes | n/a | The name of the application using this SDK. Will be used as part of the metrics sent to Unleash Proxy. Will also be part of the Unleash Context. | +| url | yes | n/a | The Unleash URL to connect to. E.g.: `https://examples.com/api/front-end` | +| clientKey | yes | n/a | The Unleash API Secret to be used | +| appName | yes | n/a | The name of the application using this SDK. Will be used as part of the metrics sent to Unleash. Will also be part of the Unleash Context. | | context | no | `{}` | The initial Unleash context. This will be used as the initial context for all feature toggle evaluations. The `appName` and `environment` options will automatically be populated with the values you pass for those options. | | refreshInterval | no | `30` | How often, in seconds, the SDK should check for updated toggle configuration. If set to 0 will disable checking for updates | | disableRefresh | no | `false` | If set to true, the client will not check for updated toggle configuration | -| metricsInterval | no | `60` | How often, in seconds, the SDK should send usage metrics back to Unleash Proxy. It will be started after the initial metrics report, which is sent after the configured `metricsIntervalInitial` | +| metricsInterval | no | `60` | How often, in seconds, the SDK should send usage metrics back to Unleash. It will be started after the initial metrics report, which is sent after the configured `metricsIntervalInitial` | | metricsIntervalInitial | no | `2` | How long the SDK should wait for the first metrics report back to the Unleash API. If you want to disable the initial metrics call you can set it to 0. | | disableMetrics | no | `false` | Set this option to `true` if you want to disable usage metrics | | storageProvider | no | `LocalStorageProvider` in browser, `InMemoryStorageProvider` otherwise | Allows you to inject a custom storeProvider | @@ -131,8 +130,8 @@ The Unleash SDK takes the following options: | createAbortController | no | `() => new AbortController()` | Allows you to override the default `AbortController` creation. Used to cancel requests with outdated context. Set it to `() => null` if you don't want to handle it. | | bootstrap | no | `[]` | Allows you to bootstrap the cached feature toggle configuration. | | bootstrapOverride | no| `true` | Should the bootstrap automatically override cached data in the local-storage. Will only be used if bootstrap is not an empty array. | -| headerName | no| `Authorization` | Which header the SDK should use to authorize with Unleash / Unleash Proxy. The header will be given the `clientKey` as its value. | -| customHeaders | no| `{}` | Additional headers to use when making HTTP requests to the Unleash proxy. In case of name collisions with the default headers, the `customHeaders` value will be used if it is not `null` or `undefined`. `customHeaders` values that are `null` or `undefined` will be ignored. | +| headerName | no| `Authorization` | Which header the SDK should use to authorize with Unleash / Unleash Edge. The header will be given the `clientKey` as its value. | +| customHeaders | no| `{}` | Additional headers to use when making HTTP requests to Unleash. In case of name collisions with the default headers, the `customHeaders` value will be used if it is not `null` or `undefined`. `customHeaders` values that are `null` or `undefined` will be ignored. | | impressionDataAll | no| `false` | Allows you to trigger "impression" events for **all** `getToggle` and `getVariant` invocations. This is particularly useful for "disabled" feature toggles that are not visible to frontend SDKs. | | environment | no | `default` | Sets the `environment` option of the [Unleash context](https://docs.getunleash.io/reference/unleash-context). This does **not** affect the SDK's [Unleash environment](https://docs.getunleash.io/reference/environments). | | usePOSTrequests | no | `false` | Configures the client to use POST requests instead of GET when requesting enabled features. This is helpful when sensitive information (like user email, when used as a user ID) is passed in the context to avoid leaking it in the URL. NOTE: Post requests are not supported by the frontend api built into Unleash. | @@ -145,7 +144,7 @@ This is a neat way to update a single page app when toggle state updates. ```js unleash.on('update', () => { - const myToggle = unleash.isEnabled('proxy.demo'); + const myToggle = unleash.isEnabled('js.demo'); //do something useful }); ``` @@ -155,7 +154,7 @@ unleash.on('update', () => { - **error** - emitted when an error occurs on init, or when fetch function fails, or when fetch receives a non-ok response object. The error object is sent as payload. - **initialized** - emitted after the SDK has read local cached data in the storageProvider. - **ready** - emitted after the SDK has successfully started and performed the initial fetch of flags via the network (Edge, proxy, or front-end API). When bootstrapping, the client can emit this event twice: once when the bootstrapped flags are loaded, and once on first successful connection to Unleash. -- **update** - emitted every time the Unleash Proxy return a new feature toggle configuration. The SDK will emit this event as part of the initial fetch from the SDK. +- **update** - emitted every time Unleash returns a new feature toggle configuration. The SDK will emit this event as part of the initial fetch from the SDK. - **recovered** - emitted when the SDK has recovered from an error. This event will only be emitted if the SDK has previously emitted an error. - **sent** - emitted when the SDK has successfully sent metrics to Unleash.