From b5a36a6d42ed397b9aa2e7addd127dc42a3d27ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivar=20Conradi=20=C3=98sthus?= Date: Tue, 4 May 2021 16:08:21 +0200 Subject: [PATCH] chore: fix SDK docs --- docs/sdks/dot_net.md | 23 +++--- docs/sdks/go.md | 20 ++--- docs/sdks/index.md | 35 +++++++++ docs/sdks/java.md | 24 +++--- docs/sdks/node.md | 29 ++++---- docs/sdks/python.md | 17 +++-- docs/sdks/ruby.md | 11 ++- docs/user_guide/client-sdk.md | 25 ++----- docs/user_guide/connect-sdk.md | 130 ++------------------------------- 9 files changed, 111 insertions(+), 203 deletions(-) create mode 100644 docs/sdks/index.md diff --git a/docs/sdks/dot_net.md b/docs/sdks/dot_net.md index 0f1c46cfe4..3d9d493cc8 100644 --- a/docs/sdks/dot_net.md +++ b/docs/sdks/dot_net.md @@ -5,13 +5,12 @@ title: .net SDK In this guide we explain how to use feature toggles in a .NET application using Unleash-hosted. We will be using the open source Unleash [.net Client SDK](https://github.com/Unleash/unleash-client-dotnet). -> **Important details** +> **Required details** > ->Make sure you have the following details available: +> - **API URL** – Where you should connect your client SDK +> - **API Secret** – Your API secret required to connect to your instance. > ->- **API URL** – Where you should connect your client SDK ->- **API Secret** – Your API secret required to connect to your instance. ->You can find this information in your “Instance admin” available in your Unleash management UI. +> You can find this information in the “Admin” section Unleash management UI. ## Step 1: Install client SDK @@ -40,32 +39,32 @@ var settings = new UnleashSettings() IUnleash unleash = new DefaultUnleash(settings); ``` -In your app you typically just want one instance of Unleash, and inject that where you need it. +In your app you typically just want one instance of Unleash, and inject that where you need it. You should change the URL and the Authorization header (API secret) with the correct values for your instance, which you may locate under “Instance admin” in the menu. ## Step 3: Use the feature toggle -Now that we have initialized the client 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 request. +Now that we have initialized the client 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 request. ```csharp -if (unleash.IsEnabled("Demo")) +if (unleash.IsEnabled("Demo")) { //do some magic -} -else +} +else { //do old boring stuff } ``` -Pleas note the client SDK will synchronize with the Unleash-hosted API on initialization, and thus it can take a few milliseconds the first time before the client has the correct state. You can use the *SynchronousInitialization* option to block the client until it has successfully synced with the server. +Pleas note the client SDK will synchronize with the Unleash-hosted API on initialization, and thus it can take a few milliseconds the first time before the client has the correct state. You can use the _SynchronousInitialization_ option to block the client until it has successfully synced with the server. Read more about the [Unleash architecture](https://www.unleash-hosted.com/articles/our-unique-architecture) to learn how it works in more details ## Step 4: Provide Unleash Context -It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the activation strategies, which are implemented in the client SDK. +It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the activation strategies, which are implemented in the client SDK. The activation strategies is an implementation of rules based on data, which you provide as part of the Unleash Context. diff --git a/docs/sdks/go.md b/docs/sdks/go.md index 8d83f79c4f..cba4f1126c 100644 --- a/docs/sdks/go.md +++ b/docs/sdks/go.md @@ -3,6 +3,13 @@ id: go_sdk title: GO SDK --- +> **Required details** +> +> - **API URL** – Where you should connect your client SDK +> - **API Secret** – Your API secret required to connect to your instance. +> +> You can find this information in the “Admin” section Unleash management UI. + ### 1. Install unleash-client-go To install the latest version of the client use: @@ -38,8 +45,7 @@ func init() { ### 3. Use unleash -After you have initialized the unleash-client you can easily check if a feature -toggle is enabled or not. +After you have initialized the unleash-client you can easily check if a feature toggle is enabled or not. ```go unleash.IsEnabled("app.ToggleX") @@ -47,15 +53,13 @@ unleash.IsEnabled("app.ToggleX") ### 4. Stop unleash -To shut down the client (turn off the polling) you can simply call the -destroy-method. This is typically not required. +To shut down the client (turn off the polling) you can simply call the destroy-method. This is typically not required. unleash.Close() ### Built in activation strategies -The Go client comes with implementations for the built-in activation strategies -provided by unleash. +The Go client comes with implementations for the built-in activation strategies provided by unleash. - DefaultStrategy - UserIdStrategy @@ -70,9 +74,7 @@ Read more about the strategies in [activation-strategy.md](). ### Unleash context -In order to use some of the common activation strategies you must provide a -[unleash-context](https://github.com/Unleash/unleash/blob/master/docs/unleash-context.md). -This client SDK allows you to send in the unleash context as part of the `isEnabled` call: +In order to use some of the common activation strategies you must provide a [unleash-context](https://github.com/Unleash/unleash/blob/master/docs/unleash-context.md). This client SDK allows you to send in the unleash context as part of the `isEnabled` call: ```go ctx := context.Context{ diff --git a/docs/sdks/index.md b/docs/sdks/index.md new file mode 100644 index 0000000000..4ebbc451cb --- /dev/null +++ b/docs/sdks/index.md @@ -0,0 +1,35 @@ +--- +id: index +title: Introduction +--- + +In order to connect your application to Unleash you need to use a client SDK (software developer kit) for your programming language. The SDK will handle connecting to the Unleash server instance and retrieve feature toggles based upon your configuration. Both open-source and the Unleash enterprise offering utilize the same set of client SDKs. + +If you are an Unleash customer, our hosted instances will always be a protected instance, you will therefore have to specify a client secret as the authorization header when you are connecting your client SDK, which you will receive from us when you sign up for one of our packages. In the open source version you must generate your own secret. + +On this page you will find examples for connecting your application to the demo instance. If you are connecting to your own private instance you will have to remember to replace the client secret and the API url given in the examples. + +We have examples for all official client SDKs: + +- [Java SDK](./java_sdk) +- [Node.js SDK](./node_sdk) +- [Go SDK](./go_sdk) +- [Ruby SDK](./ruby_sdk) +- [Python SDK](./python_sdk) +- [.Net SDK](./dot_net_sdk) +- [Javascript SDK](https://github.com/unleash-hosted/unleash-proxy-client-js) (Used by single-page applications) + +### Clients written by awesome enthusiasts: + +- [cognitedata/unleash-client-rust](https://github.com/cognitedata/unleash-client-rust) (Rust) +- [silvercar/unleash-client-kotlin](https://github.com/silvercar/unleash-client-kotlin) (Kotlin) +- [uekoetter.dev/unleash-client-dart](https://pub.dev/packages/unleash) (Dart) +- [minds/unleash-client-php](https://gitlab.com/minds/unleash-client-php) (PHP) +- [Stogon/unleash-bundle](https://git.stogon.io/Stogon/unleash-bundle/) (PHP - Symfony) +- [afontaine/unleash_ex](https://gitlab.com/afontaine/unleash_ex) (Elixir) +- [mikefrancis/laravel-unleash](https://github.com/mikefrancis/laravel-unleash) (Laravel - PHP) +- [AppsFlyer/clojure-unleash](https://github.com/AppsFlyer/unleash-client-clojure) (Clojure) +- [pmb0/nestjs-unleash](https://github.com/pmb0/nestjs-unleash) (NestJS - Node.js) +- _...your implementation for your favorite language._ + +When you get access to your instance – we will provide you with your Client secret and your API url for your instance. diff --git a/docs/sdks/java.md b/docs/sdks/java.md index 2fca401ddd..b324ba6f4f 100644 --- a/docs/sdks/java.md +++ b/docs/sdks/java.md @@ -5,20 +5,18 @@ title: Java SDK In this guide we explain how to use feature toggles in a Java application using Unleash-hosted. We will be using the open source Unleash [Java Client SDK](https://github.com/Unleash/unleash-client-java). -> **Important details** +> **Required details** > ->Make sure you have the following details available: +> - **API URL** – Where you should connect your client SDK +> - **API Secret** – Your API secret required to connect to your instance. > ->- **API URL** – Where you should connect your client SDK ->- **API Secret** – Your API secret required to connect to your instance. ->You can find this information in your “Instance admin” available in your Unleash management UI. - +> You can find this information in the “Admin” section Unleash management UI. ## Step 1: Install the client SDK First we must add Unleash Client SDK as a dependency to your project. Below is an example of how you would add it to your pom.xml in Java: -```xml +```xml no.finn.unleash unleash-client-java @@ -42,15 +40,13 @@ UnleashConfig unleashConfig = UnleashConfig.builder() Unleash unleash = new DefaultUnleash(config); ``` -In your app you typically just want one instance of Unleash, and inject that where you need it. You will typically use a dependency injection frameworks such as Spring or Guice to manage this. +In your app you typically just want one instance of Unleash, and inject that where you need it. You will typically use a dependency injection frameworks such as Spring or Guice to manage this. You should change the URL and the Authorization header (API secret) with the correct values for your instance, which you may locate under “Instance admin” in the menu. - - ## Step 3: Use the feature toggle -Now that we have initialized the client 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 request. +Now that we have initialized the client 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 request. ```java if(unleash.isEnabled("AwesomeFeature")) { @@ -60,13 +56,13 @@ if(unleash.isEnabled("AwesomeFeature")) { } ``` -Pleas note the client SDK will synchronize with the Unleash-hosted API on initialization, and thus it can take a few milliseconds the first time before the client has the correct state. You can use the *synchronousFetchOnInitialisation* option to block the client until it has successfully synced with the server. +Pleas note the client SDK will synchronize with the Unleash-hosted API on initialization, and thus it can take a few milliseconds the first time before the client has the correct state. You can use the _synchronousFetchOnInitialisation_ option to block the client until it has successfully synced with the server. Read more about the [Unleash architecture](https://www.unleash-hosted.com/articles/our-unique-architecture) to learn how it works in more details ## Step 4: Provide Unleash Context -It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/control_rollout), which are implemented in the client SDK. +It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/control_rollout), which are implemented in the client SDK. The activation strategies is an implementation of rules based on data, which you provide as part of the Unleash Context. @@ -99,6 +95,6 @@ UnleashConfig config = new UnleashConfig.Builder() Unleash unleash = new DefaultUnleash(config); -// Anywhere in the code unleash will get the unleash context from your registered provider. +// Anywhere in the code unleash will get the unleash context from your registered provider. unleash.isEnabled("someToggle"); ``` diff --git a/docs/sdks/node.md b/docs/sdks/node.md index 9a9d026927..7a93926172 100644 --- a/docs/sdks/node.md +++ b/docs/sdks/node.md @@ -5,13 +5,12 @@ title: Node SDK In this guide we explain how to use feature toggles in a Node application using Unleash-hosted. We will be using the open source Unleash [Node.js Client SDK](https://github.com/Unleash/unleash-client-node). -> **Important details** +> **Required details** > ->Make sure your have the following details available: +> - **API URL** – Where you should connect your client SDK +> - **API Secret** – Your API secret required to connect to your instance. > ->- **API URL** – Where you should connect your client SDK ->- **API Secret** – Your API secret required to connect to your instance. ->You can find this information in your “Instance admin” available in your Unleash management UI. +> You can find this information in the “Admin” section Unleash management UI. ## Step 1: Install the client SDK @@ -27,32 +26,30 @@ Next we must initialize the client SDK in the application: ```js const unleash = require('unleash-client'); - + unleash.initialize({ url: 'https://YOUR-API-URL', appName: 'my-node-name', environment: process.env.APP_ENV, - customHeaders: {'Authorization': 'SOME-SECRET'} + customHeaders: { Authorization: 'SOME-SECRET' }, }); ``` The example code above will initialize the client SDK, and connect to the Unleash-hosted demo instance. It also uses the API token for the demo instance. You should change the URL and the Authorization header (API token) with the correct values for your instance, which you may locate under “Instance admin” in the menu. -Please also pay attention to the “environment” option. Setting this will allow you to use [strategy constraints](../user_guide/strategy-constraints) which enables different roll-out strategies per environment. - - +Please also pay attention to the “environment” option. Setting this will allow you to use [strategy constraints](../user_guide/strategy-constraints) which enables different roll-out strategies per environment. ## Step 3: Use the feature toggle -Now that we have initialized the client SDK in our application 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 request. +Now that we have initialized the client SDK in our application 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 request. ```js setInterval(() => { - if(unleash.isEnabled('DemoToggle')) { - console.log('Toggle enabled'); - } else { - console.log('Toggle disabled'); - } + if (unleash.isEnabled('DemoToggle')) { + console.log('Toggle enabled'); + } else { + console.log('Toggle disabled'); + } }, 1000); ``` diff --git a/docs/sdks/python.md b/docs/sdks/python.md index 3bb6ceda79..5096ae48c6 100644 --- a/docs/sdks/python.md +++ b/docs/sdks/python.md @@ -3,17 +3,24 @@ id: python_sdk title: Python SDK --- -```java +> **Required details** +> +> - **API URL** – Where you should connect your client SDK +> - **API Secret** – Your API secret required to connect to your instance. +> +> You can find this information in the “Admin” section Unleash management UI. + +```python from UnleashClient import UnleashClient - + client = UnleashClient( url="", app_name="my-python-app", custom_headers={'Authorization': ''}) - + client.initialize_client() - + client.is_enabled("unleash.beta.variants") ``` -Read more at [github.com/Unleash/unleash-client-python](https://github.com/Unleash/unleash-client-python) \ No newline at end of file +Read more at [github.com/Unleash/unleash-client-python](https://github.com/Unleash/unleash-client-python) diff --git a/docs/sdks/ruby.md b/docs/sdks/ruby.md index f9ebf927c7..1f2bb9ae6d 100644 --- a/docs/sdks/ruby.md +++ b/docs/sdks/ruby.md @@ -3,9 +3,16 @@ id: ruby_sdk title: Ruby SDK --- +> **Required details** +> +> - **API URL** – Where you should connect your client SDK +> - **API Secret** – Your API secret required to connect to your instance. +> +> You can find this information in the “Admin” section Unleash management UI. + ```sh require 'unleash' - + @unleash = Unleash::Client.new( url: '', app_name: 'simple-test', @@ -13,4 +20,4 @@ title: Ruby SDK ) ``` -Read more at [github.com/Unleash/unleash-client-ruby](https://github.com/Unleash/unleash-client-ruby) \ No newline at end of file +Read more at [github.com/Unleash/unleash-client-ruby](https://github.com/Unleash/unleash-client-ruby) diff --git a/docs/user_guide/client-sdk.md b/docs/user_guide/client-sdk.md index c6f7c239e2..cf22787224 100644 --- a/docs/user_guide/client-sdk.md +++ b/docs/user_guide/client-sdk.md @@ -3,25 +3,10 @@ id: client_sdk title: Client SDK --- -To use Unleash in your application, you will need an Unleash Client SDK. Unleash has official client SDKs for Java, Node.js, Go, Ruby, Python and .Net. We will be happy to add implementations in other languages written by you! These libraries make it very easy to use Unleash in your application. + -### Official client SDKs: +Please see /docs/sdks -- [unleash/unleash-client-java](https://github.com/unleash/unleash-client-java) -- [unleash/unleash-client-node](https://github.com/unleash/unleash-client-node) -- [unleash/unleash-client-go](https://github.com/unleash/unleash-client-go) -- [unleash/unleash-client-ruby](https://github.com/unleash/unleash-client-ruby) -- [unleash/unleash-client-python](https://github.com/Unleash/unleash-client-python) -- [unleash/unleash-client-core](https://github.com/Unleash/unleash-client-core) (.Net Core) - -### Clients written by awesome enthusiasts: - -- [cognitedata/unleash-client-rust](https://github.com/cognitedata/unleash-client-rust) (Rust) -- [silvercar/unleash-client-kotlin](https://github.com/silvercar/unleash-client-kotlin) (Kotlin) -- [uekoetter.dev/unleash-client-dart](https://pub.dev/packages/unleash) (Dart) -- [minds/unleash-client-php](https://gitlab.com/minds/unleash-client-php) (PHP) -- [afontaine/unleash_ex](https://gitlab.com/afontaine/unleash_ex) (Elixir) -- [mikefrancis/laravel-unleash](https://github.com/mikefrancis/laravel-unleash) (Laravel - PHP) -- [AppsFlyer/clojure-unleash](https://github.com/AppsFlyer/unleash-client-clojure) (Clojure) -- [pmb0/nestjs-unleash](https://github.com/pmb0/nestjs-unleash) (NestJS - Node.js) -- _...your implementation for your favorite language._ + diff --git a/docs/user_guide/connect-sdk.md b/docs/user_guide/connect-sdk.md index ab7279395f..15ab0fb9f0 100644 --- a/docs/user_guide/connect-sdk.md +++ b/docs/user_guide/connect-sdk.md @@ -3,130 +3,10 @@ id: connect_sdk title: Connect your SDK --- -In order to connect your application to Unleash you need to use a client SDK (software developer kit) for your programming language. The SDK will handle connecting to the Unleash server instance and retrieve feature toggles based upon your configuration. Both open-source and the Unleash enterprise offering utilize the same set of client SDKs. + -If you are an Unleash customer, our hosted instances will always be a protected instance, you will therefore have to specify a client secret as the authorization header when you are connecting your client SDK, which you will receive from us when you sign up for one of our packages. In the open source version you must generate your own secret. +Please see /docs/sdks -On this page you will find examples for connecting your application to the demo instance. If you are connecting to your own private instance you will have to remember to replace the client secret and the API url given in the examples. - -We have examples for all official client SDKs: - -- [Java SDK](https://github.com/Unleash/unleash-client-java) -- [Node.js SDK](https://github.com/Unleash/unleash-client-node) -- [.NET SDK](https://github.com/Unleash/unleash-client-dotnet) -- [Go SDK](https://github.com/Unleash/unleash-client-go) -- [Ruby SDK](https://github.com/Unleash/unleash-client-ruby) -- [Python SDK](https://github.com/Unleash/unleash-client-python) - -When you get access to your instance – we will provide you with your Client secret and your API url for your instance. - -## Demo instance secrets -Our demo instance has the following settings – use these in case you would like to connect your test-app to our demo environment. - -### Client secret -```sh -56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d -``` - -### API url: -```sh -https://app.unleash-hosted.com/demo/api/ -``` - -### Test with curl: -```sh -curl https://app.unleash-hosted.com/demo/api/client/features \ --H "Authorization: 56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d"; -``` - -## Java SDK -```java -UnleashConfig unleashConfig = UnleashConfig.builder() - .appName("my.java-app") - .instanceId("your-instance-1") - .unleashAPI("") - .customHttpHeader("Authorization", "") - .build(); - - Unleash unleash = new DefaultUnleash(config); -``` -Read more at [github.com/Unleash/unleash-client-java](https://github.com/Unleash/unleash-client-java) - -## Node.js SDK - -```js -const unleash = require('unleash-client'); - -unleash.initialize({ - url: '', - appName: 'my-node-name', - instanceId: 'my-unique-instance-id', - customHeaders: {'Authorization': ''} -}); -``` -Read more at [github.com/Unleash/unleash-client-node](https://github.com/Unleash/unleash-client-node) - -## Go SDK -```golang -import ( - "github.com/Unleash/unleash-client-go/v3" -) - -func init() { - unleash.Initialize( - unleash.WithAppName("my-node-app"), - unleash.WithUrl(""), - unleash.WithCustomHeaders(http.Header{"Authorization": {""}}), - ) -} -``` -Read more at [github.com/Unleash/unleash-client-go](https://github.com/Unleash/unleash-client-go) - -## Ruby SDK -```ruby - - - require 'unleash' - - @unleash = Unleash::Client.new( - url: '', - app_name: 'simple-test', - custom_http_headers = {'Authorization': ''}, - ) -``` -Read more at [github.com/Unleash/unleash-client-ruby](https://github.com/Unleash/unleash-client-ruby) - -## Python SDK -```python - - from UnleashClient import UnleashClient - - client = UnleashClient( - url="", - app_name="my-python-app", - custom_headers={'Authorization': ''}) - - client.initialize_client() - - client.is_enabled("unleash.beta.variants") -``` - -Read more at [github.com/Unleash/unleash-client-python](https://github.com/Unleash/unleash-client-python) - -## .NET SDK -```csharp - var settings = new UnleashSettings() - { - AppName = "dotnet-test", - InstanceTag = "instance z", - UnleashApi = new Uri(""), - SendMetricsInterval = TimeSpan.FromSeconds(20), - CustomHttpHeaders = new Dictionary() - { - {"Authorization","" } - } - }; - - var unleash = new DefaultUnleash(settings); -``` -Read more at [https://github.com/Unleash/unleash-client-dotnet](https://github.com/Unleash/unleash-client-dotnet) +