From dd08e9da38ffdf0c584f193e41adc420a2a6fbf9 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 6 Dec 2021 12:20:46 +0100 Subject: [PATCH 1/8] chore: Fix syntax highlighting for a json code snippet. --- website/docs/user_guide/native-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/user_guide/native-apps.md b/website/docs/user_guide/native-apps.md index b977b03504..fcfc661aab 100644 --- a/website/docs/user_guide/native-apps.md +++ b/website/docs/user_guide/native-apps.md @@ -23,7 +23,7 @@ https://hostname.com/api/proxy?appName=webapp&userId=123&country=NO The Proxy will return a list of all the active feature toggles, including variants, available. See an example below -```sh +```json { "toggles": [ { From 24bf9b7012638eacfd349985f32d17c688a9d546 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 6 Dec 2021 12:35:00 +0100 Subject: [PATCH 2/8] docs: explain what the proxy configuration variables are. --- website/docs/sdks/unleash-proxy.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index ff61b1175e..4c45907158 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -23,7 +23,29 @@ _The Unleash Proxy uses the Unleash SDK and exposes a simple API_. The Proxy wil The Unleash Proxy is Open Source and [available on github](https://github.com/Unleash/unleash-proxy). You can either run it as a docker image or as part of a [node.js express application](https://github.com/Unleash/unleash-proxy#run-with-nodejs). -The easies way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy). +### Configuration variables + +Regardless of how you choose to run the it, the proxy will need access to these three variables: + +- **`unleashUrl`** / **`UNLEASH_URL`** + + The URL of your Unleash instance's API. For instance, to connect to the [Unleash demo app](https://app.unleash-hosted.com/demo/), you would use `https://app.unleash-hosted.com/demo/api/` + +- **`unleashApiToken`** / **`UNLEASH_API_TOKEN`** + + The API token to connect to your Unleash project. For more information on how these work and how to create them, check out the [API token documentation](../user_guide/token.md). + +- **`proxySecrets`** / **`UNLEASH_PROXY_SECRETS`** + + A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` . If you query the proxy directly via HTTP, this is the `authorization` header. + + When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. + +For more information, check out the [documentation on GitHub](https://github.com/Unleash/unleash-proxy). + +### Running the proxy via Docker + +The easiest way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy). **Step 1: Pull** From a03e7927bb2ad4fe0a11ab05996f5d46a6898bc1 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 6 Dec 2021 12:58:09 +0100 Subject: [PATCH 3/8] docs: JS proxy client: explain client keys --- website/docs/sdks/proxy-javascript.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/website/docs/sdks/proxy-javascript.md b/website/docs/sdks/proxy-javascript.md index fd57286d60..47a0faff0e 100644 --- a/website/docs/sdks/proxy-javascript.md +++ b/website/docs/sdks/proxy-javascript.md @@ -5,12 +5,14 @@ title: JavaScript Proxy SDK In this guide we explain how to use feature toggles in a Single Page App via [The Unleash Proxy](/sdks/unleash-proxy). You can also checkout the source code for the [JavaScript Proxy SDK](https://github.com/unleash/unleash-proxy-client-js). -### Introduction {#introduction} +## Introduction {#introduction} For single-page apps we have a tiny proxy-client in JavaScript, without any external dependencies, except from browser APIs. This client will store toggles relevant for the current user in local-storage and synchronize with the Unleash Proxy in the background. This means we can bootstrap the toggles for a specific use the next time the user visits the 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** ``` @@ -19,7 +21,7 @@ npm install unleash-proxy-client **Step 2: Initialize the SDK** -You need to have a Unleash-hosted instance, and the proxy need to be enabled. In addition you will need a proxy-specific clientKey in order to connect to the Unleash-hosted Proxy. +You need to have an Unleash-hosted instance, and the proxy need to be enabled. In addition you will need a proxy-specific `clientKey` in order to connect to the Unleash-hosted Proxy. For more on how to set up client keys, [consult the Unleash Proxy docs](unleash-proxy.md#configuration-variables). ```js import { UnleashClient } from 'unleash-proxy-client'; From d936a0d4edfe5701fb5947c6c3ae2004a4fd7964 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 6 Dec 2021 12:58:58 +0100 Subject: [PATCH 4/8] docs: Android SDK: reformat and add more details on client secrets --- website/docs/sdks/android-proxy.md | 38 +++++++++++++++++++----------- website/docs/sdks/unleash-proxy.md | 2 +- 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/website/docs/sdks/android-proxy.md b/website/docs/sdks/android-proxy.md index ff550e7a66..e43a99ac5f 100644 --- a/website/docs/sdks/android-proxy.md +++ b/website/docs/sdks/android-proxy.md @@ -5,9 +5,14 @@ title: Android Proxy SDK In this guide we'll explain how to use feature toggles in an Android application using Unleash's [Android Proxy SDK](https://github.com/Unleash/unleash-android-proxy-sdk) and the [Unleash Proxy](https://github.com/Unleash/unleash-proxy). -> You will need your `PROXY_URL` and your `PROXY_SECRET`. Refer to the [Proxy documentation](/sdks/unleash-proxy) -# Step 1: Install the proxy SDK +:::note +The Android proxy SDK requires Unleash Proxy to function. You'll need the proxy's URL and a configured proxy secret. Refer to the [proxy documentation](/sdks/unleash-proxy) for how to set it up and [how to configure the proxy secrets](/sdks/unleash-proxy#configuration-variables). +::: + +## How to use the Android Proxy SDK + +### Step 1: Install the proxy SDK First we must add unleash-android-proxy-sdk as a dependency to our project. @@ -27,7 +32,7 @@ In maven ``` -# Step 2: Enable internet +### Step 2: Enable internet > NB - Your app will need internet permission in order to reach the proxy. So in your manifest add @@ -35,7 +40,7 @@ In maven ``` -# Step 3: Configure Context +### Step 3: Configure Context Since the proxy works by evaluating all feature toggles server side and returning the evaluated toggles back to the client, we'll need to configure the context to send to the proxy for evaluation. @@ -49,11 +54,16 @@ val myAppContext = UnleashContext.newBuilder() .build() ``` -# Step 4: Configure the Client +### Step 4: Configure the Client -Configuring the client includes adding the URL for your proxy host, your proxy secret and deciding how you want to load the toggle status. As of v0.1 the SDK supports an automatic polling with an adjustable poll period or loading the state from disk. Most users will probably use the polling client, but it's nice to know that you can instantiate your client without actually needing Internet if you choose loading from File +To create a client, use the `UnleashConfig.newBuilder` method. When building a configuration, you'll need to provide it with: +- `proxyUrl`: the URL your proxy is available at +- `clientSecret`: the [proxy secret](/sdks/unleash-proxy#configuration-variables) you wish to use +- `pollMode`: how you want to load the toggle status -# Step 4a: Configure client polling proxy +As of v0.1 the SDK supports an automatic polling with an adjustable poll period or loading the state from disk. Most users will probably use the polling client, but it's nice to know that you can instantiate your client without actually needing Internet if you choose loading from File + +#### Step 4a: Configure client polling proxy Configuring a client with a 60 seconds poll interval @@ -63,7 +73,7 @@ import io.getunleash.polling.PollingModes val unleashConfig = UnleashConfig.newBuilder() .proxyUrl("URL to your proxy installation") - .clientSecret("yourProxyApiKey") + .clientSecret("yourProxySecret") .pollMode(PollingModes.autoPoll(Duration.ofSeconds(60)) { // This lambda will be called every time polling the server updates the toggle state featuresUpdated() @@ -71,7 +81,7 @@ val unleashConfig = UnleashConfig.newBuilder() .build() ``` -# Step 4b: Configure client loading toggles from a file +#### Step 4b: Configure client loading toggles from a file If you need to have a known state for your UnleashClient, you can perform a query against the proxy using your HTTP client of choice and save the output as a json file. Then you can tell Unleash to use this file to setup toggle states. @@ -89,7 +99,7 @@ val unleashConfig = UnleashConfig.newBuilder() .build() ``` -# Step 5: Instantiate the client +### Step 5: Instantiate the client Having created your `UnleashContext` and your `UnleashConfig` you can now instantiate your client. Make sure you only do this once, and pass the instantiated client to classes/functions that need it. @@ -99,7 +109,7 @@ import io.getunleash.UnleashClient val unleashClient = UnleashClient(config = unleashConfig, context = myAppContext) ``` -# Step 6: Use the feature toggle +### Step 6: Use the feature toggle Now that we have initialized the proxy SDK we can start using feature toggles defined in Unleash in our application. To achieve this we have the “isEnabled” method available, which will allow us to check the value of a feature toggle. This method will return true or false based on whether the feature should be enabled or disabled for the current state. @@ -111,14 +121,14 @@ if (unleashClient.isEnabled("AwesomeFeature")) { } ``` -# Updates +## Updates When using the AutoPoll mode you are able to pass in a listener which will get notified everytime our toggles changes, allowing you to recheck your toggles. For an example, see our [android-sample-app](https://github.com/Unleash/unleash-android-proxy-sdk/blob/main/samples/android/app/src/main/java/com/example/unleash/MainActivity.kt) -# KDoc +## KDoc KDoc for the api is available at [https://docs.getunleash.io/unleash-android-proxy-sdk](https://docs.getunleash.io/unleash-android-proxy-sdk) -# Github +## Github Readme for the client and source code is available at [https://github.com/Unleash/unleash-android-proxy-sdk](https://github.com/Unleash/unleash-android-proxy-sdk) diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 4c45907158..3ee579e180 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -37,7 +37,7 @@ Regardless of how you choose to run the it, the proxy will need access to these - **`proxySecrets`** / **`UNLEASH_PROXY_SECRETS`** - A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` . If you query the proxy directly via HTTP, this is the `authorization` header. + A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret` . If you query the proxy directly via HTTP, this is the `authorization` header. When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. From b46afd8887ea5f7d3565729a0e63ed472fd84f06 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 6 Dec 2021 13:16:54 +0100 Subject: [PATCH 5/8] docs: react proxy sdk: explain clientKey and other config vars. --- website/docs/sdks/proxy-react.md | 46 +++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/website/docs/sdks/proxy-react.md b/website/docs/sdks/proxy-react.md index 7954c13327..a5474b6c9e 100644 --- a/website/docs/sdks/proxy-react.md +++ b/website/docs/sdks/proxy-react.md @@ -3,19 +3,45 @@ id: proxy-react title: React proxy SDK --- -> This library is meant to be used with the [unleash-proxy](https://github.com/Unleash/unleash-proxy). The proxy application layer will sit between your unleash instance and your client applications, and provides performance and security benefits. DO NOT TRY to connect this library directly to the unleash instance, as the datasets follow different formats because the proxy only returns evaluated toggle information. +This library is meant to be used with the [unleash-proxy](https://github.com/Unleash/unleash-proxy). The proxy application layer will sit between your unleash instance and your client applications, and provides performance and security benefits. DO NOT TRY to connect this library directly to the unleash instance, as the datasets follow different formats because the proxy only returns evaluated toggle information. -# Installation +For more detailed information, check out [the React Proxy SDK on GitHub](https://github.com/Unleash/proxy-client-react). -``` + +## Installation + +```sh npm install @unleash/proxy-client-react // or yarn add @unleash/proxy-client-react ``` -Import the provider like this in your entrypoint file (typically index.js/ts): +## Initialize the client -```js +The snippet below shows you how to initialize the client. We recommend that you do this in your entry point file (typically index.js/ts) to ensure that you only have _one_ instance of it. + +The configuration variables are: +- **`url`** + + Your proxy's URL. +- **`clientKey`** + + One of your proxy's [designated client keys (also known as proxy secrets)](unleash-proxy#configuration-variables). + +- **`refreshInterval`** + + How often (in seconds) the client should poll the proxy for updates. + +- **`appName`** + + The name of your application. It's only used for identifying your application and can be whatever you want it to be. + +- **`environment`** + + The environment that your application runs in. This corresponds to the environment field in [the Unleash Context](../user_guide/unleash-context.md). Note that this is separate from the newer [Environments feature](../user_guide/environments.md). + + +```jsx import FlagProvider from '@unleash/proxy-client-react'; const config = { @@ -36,9 +62,11 @@ ReactDOM.render( ); ``` +## How to check feature toggle states + To check if a feature is enabled: -```js +```jsx import { useFlag } from '@unleash/proxy-client-react'; const TestComponent = () => { @@ -55,7 +83,7 @@ export default TestComponent; To check variants: -```js +```jsx import { useVariant } from '@unleash/proxy-client-react'; const TestComponent = () => { @@ -72,11 +100,11 @@ const TestComponent = () => { export default TestComponent; ``` -## Updating context +## How to update the Unleash Context Follow the following steps in order to update the unleash context: -```js +```jsx import { useUnleashContext, useFlag } from '@unleash/proxy-client-react' const MyComponent = ({ userId }) => { From acedb240caeb2684b843e0fe45092a0b791573b2 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 6 Dec 2021 13:24:59 +0100 Subject: [PATCH 6/8] docs: iOS proxy: add info about client keys and environments. --- website/docs/sdks/proxy-ios.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/website/docs/sdks/proxy-ios.md b/website/docs/sdks/proxy-ios.md index 9b3135bd80..182094dfcb 100644 --- a/website/docs/sdks/proxy-ios.md +++ b/website/docs/sdks/proxy-ios.md @@ -48,13 +48,27 @@ var unleash = UnleashProxyClientSwift.UnleashClient( unleash.start() ``` -In the example above we import the UnleashProxyClientSwift and instantiate the client. You need to provide the following parameters: +In the example above we import the `UnleashProxyClientSwift` and instantiate the client. You need to provide the following parameters: -- unleashUrl: the full url to your proxy instance [String] -- clientKey: the proxy key [String] -- refreshInterval: the polling interval in seconds [Int] -- appName: the application name identifier [String] -- environment: the application env [String] +- `unleashUrl` (`String`) + + the full URL to your proxy instance + +- `clientKey` (`String`) + + one of the configured [proxy keys / proxy secrets](unleash-proxy#configuration-variables) + +- `refreshInterval` (`Int`) + + the polling interval in seconds. + +- `appName` (`String`) + + the application name; only used to identify your application. + +- `environment` (`String`) + + the application environment. This corresponds to the environment field in [the Unleash Context](../user_guide/unleash-context.md). Note that this is separate from the newer [Environments feature](../user_guide/environments.md). Running `unleash.start()` will make the first request against the proxy and retrieve the feature toggle configuration, and set up the polling interval in the background. From 815fc353ec2f8189ad75fbd13fe38805f3b0a367 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 6 Dec 2021 14:06:14 +0100 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: sighphyre --- website/docs/sdks/android-proxy.md | 4 ++-- website/docs/sdks/proxy-javascript.md | 2 +- website/docs/sdks/unleash-proxy.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/sdks/android-proxy.md b/website/docs/sdks/android-proxy.md index e43a99ac5f..5e1dcb77ae 100644 --- a/website/docs/sdks/android-proxy.md +++ b/website/docs/sdks/android-proxy.md @@ -7,7 +7,7 @@ In this guide we'll explain how to use feature toggles in an Android application :::note -The Android proxy SDK requires Unleash Proxy to function. You'll need the proxy's URL and a configured proxy secret. Refer to the [proxy documentation](/sdks/unleash-proxy) for how to set it up and [how to configure the proxy secrets](/sdks/unleash-proxy#configuration-variables). +The Android proxy SDK requires the Unleash Proxy to function. You'll need the proxy's URL and a configured proxy secret. Refer to the [proxy documentation](/sdks/unleash-proxy) for how to set it up and [how to configure the proxy secrets](/sdks/unleash-proxy#configuration-variables). ::: ## How to use the Android Proxy SDK @@ -61,7 +61,7 @@ To create a client, use the `UnleashConfig.newBuilder` method. When building a c - `clientSecret`: the [proxy secret](/sdks/unleash-proxy#configuration-variables) you wish to use - `pollMode`: how you want to load the toggle status -As of v0.1 the SDK supports an automatic polling with an adjustable poll period or loading the state from disk. Most users will probably use the polling client, but it's nice to know that you can instantiate your client without actually needing Internet if you choose loading from File +As of v0.1 the SDK supports an automatic polling with an adjustable poll period or loading the state from disk. Most users will probably want to use the polling client, but it's nice to know that you can instantiate your client without actually needing Internet if you choose loading from File #### Step 4a: Configure client polling proxy diff --git a/website/docs/sdks/proxy-javascript.md b/website/docs/sdks/proxy-javascript.md index 47a0faff0e..65a1c5c393 100644 --- a/website/docs/sdks/proxy-javascript.md +++ b/website/docs/sdks/proxy-javascript.md @@ -21,7 +21,7 @@ npm install unleash-proxy-client **Step 2: Initialize the SDK** -You need to have an Unleash-hosted instance, and the proxy need to be enabled. In addition you will need a proxy-specific `clientKey` in order to connect to the Unleash-hosted Proxy. For more on how to set up client keys, [consult the Unleash Proxy docs](unleash-proxy.md#configuration-variables). +You need to have an Unleash-hosted instance, and the proxy needs to be enabled. In addition you will need a proxy-specific `clientKey` in order to connect to the Unleash-hosted Proxy. For more on how to set up client keys, [consult the Unleash Proxy docs](unleash-proxy.md#configuration-variables). ```js import { UnleashClient } from 'unleash-proxy-client'; diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 3ee579e180..e7a3a65713 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -37,7 +37,7 @@ Regardless of how you choose to run the it, the proxy will need access to these - **`proxySecrets`** / **`UNLEASH_PROXY_SECRETS`** - A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret` . If you query the proxy directly via HTTP, this is the `authorization` header. + A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret`. If you query the proxy directly via HTTP, this is the `authorization` header. When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. From b59527720448a1ec4d9e94fa1ef7a15930227bf5 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 6 Dec 2021 14:08:25 +0100 Subject: [PATCH 8/8] chore: (docs) keep list styling (internally) consistent --- website/docs/sdks/proxy-ios.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/docs/sdks/proxy-ios.md b/website/docs/sdks/proxy-ios.md index 182094dfcb..96341de427 100644 --- a/website/docs/sdks/proxy-ios.md +++ b/website/docs/sdks/proxy-ios.md @@ -52,23 +52,23 @@ In the example above we import the `UnleashProxyClientSwift` and instantiate the - `unleashUrl` (`String`) - the full URL to your proxy instance + The full URL to your proxy instance. - `clientKey` (`String`) - one of the configured [proxy keys / proxy secrets](unleash-proxy#configuration-variables) + One of the configured [proxy keys / proxy secrets](unleash-proxy#configuration-variables). - `refreshInterval` (`Int`) - the polling interval in seconds. + The polling interval in seconds. - `appName` (`String`) - the application name; only used to identify your application. + The application name; only used to identify your application. - `environment` (`String`) - the application environment. This corresponds to the environment field in [the Unleash Context](../user_guide/unleash-context.md). Note that this is separate from the newer [Environments feature](../user_guide/environments.md). + The application environment. This corresponds to the environment field in [the Unleash Context](../user_guide/unleash-context.md). Note that this is separate from the newer [Environments feature](../user_guide/environments.md). Running `unleash.start()` will make the first request against the proxy and retrieve the feature toggle configuration, and set up the polling interval in the background.