mirror of
https://github.com/Unleash/unleash.git
synced 2024-12-28 00:06:53 +01:00
d5fbd0b743
## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
80 lines
3.0 KiB
Markdown
80 lines
3.0 KiB
Markdown
---
|
|
title: JavaScript Proxy SDK
|
|
---
|
|
|
|
This guide shows you how to use feature toggles in a single-page app with the [Unleash Proxy](../unleash-proxy.md) and the [Unleash front-end API](../front-end-api). You can also check out the source code for the [JavaScript Proxy SDK](https://github.com/unleash/unleash-proxy-client-js) on GitHub for more details around the SDK.
|
|
|
|
## Introduction {#introduction}
|
|
|
|
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 proxy _or_ the Unleash front-end API) 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.
|
|
|
|
> We are looking in to also [supporting react-native](https://github.com/Unleash/unleash/issues/785) with this SDK. Reach out if you want to help us validate the implementation.
|
|
|
|
## How to use the JavaScript Proxy SDK
|
|
|
|
## Step 1: Install
|
|
|
|
```shell npm2yarn
|
|
npm install unleash-proxy-client
|
|
```
|
|
|
|
## Step 2: Initialize the SDK
|
|
|
|
```js
|
|
import { UnleashClient } from 'unleash-proxy-client';
|
|
|
|
const unleash = new UnleashClient({
|
|
url: 'https://eu.unleash-hosted.com/hosted/proxy',
|
|
clientKey: 'your-client-key',
|
|
appName: 'my-webapp',
|
|
});
|
|
|
|
// Use `updateContext` to set Unleash context fields.
|
|
unleash.updateContext({ userId: '1233' });
|
|
|
|
// Start the background polling
|
|
unleash.start();
|
|
```
|
|
|
|
### Option A: Connecting to the Unleash proxy
|
|
|
|
:::tip Prerequisites
|
|
|
|
To connect to an Unleash proxy, you need to have an instance of the proxy running.
|
|
|
|
:::
|
|
|
|
Add the proxy's URL and a [proxy client key](../api-tokens-and-client-keys.mdx#proxy-client-keys). The [_configuration_ section of the Unleash proxy docs](../unleash-proxy.md#configuration-variables) contain more info on how to configure client keys for your proxy.
|
|
|
|
### Option B: Connecting directly to Unleash
|
|
|
|
Use the url to your Unleash instance's front-end API (`<unleash-url>/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_](/how-to/how-to-create-api-tokens) guide for the necessary steps.
|
|
|
|
You might also need to set up cross-origin resource sharing (CORS) for your instance. Visit the [CORS section of the front-end API guide](../front-end-api.md#cors) for more information on setting up CORS.
|
|
|
|
### Step 3: Check if feature toggle is enabled
|
|
|
|
```js
|
|
unleash.isEnabled('proxy.demo');
|
|
```
|
|
|
|
...or get toggle variant:
|
|
|
|
```js
|
|
const variant = unleash.getVariant('proxy.demo');
|
|
if (variant.name === 'blue') {
|
|
// something with variant blue...
|
|
}
|
|
```
|
|
|
|
## Listen for updates via the EventEmitter
|
|
|
|
The client is also an event emitter. This means that your code can subscribe to updates from the client. 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');
|
|
//do something useful
|
|
});
|
|
```
|