From 82a4191e1d80c8ab6dbba69ae15efd1318fb9d05 Mon Sep 17 00:00:00 2001 From: Mateusz Kwasniewski Date: Tue, 3 Jan 2023 13:07:01 +0100 Subject: [PATCH] added flutter documentation (#2736) --- README.md | 1 + .../reference/custom-activation-strategies.md | 2 +- website/docs/reference/sdks/flutter.md | 75 +++++++++++++++++++ website/docs/reference/sdks/index.md | 1 + .../docs/reference/sdks/javascript-browser.md | 4 +- website/docs/reference/unleash-proxy.md | 2 +- website/sidebars.js | 1 + 7 files changed, 82 insertions(+), 4 deletions(-) create mode 100644 website/docs/reference/sdks/flutter.md diff --git a/README.md b/README.md index 7d07a00338..3eb9746f75 100644 --- a/README.md +++ b/README.md @@ -190,6 +190,7 @@ To connect your application to Unleash you'll need to use a client SDK for your The front-end SDKs connects via the [Unleash Proxy](https://docs.getunleash.io/reference/unleash-proxy) in order to ensure privacy, scalability and security. - [Android Proxy SDK](https://docs.getunleash.io/reference/sdks/android-proxy) +- [Flutter Proxy SDK](https://docs.getunleash.io/reference/sdks/flutter) - [iOS Proxy SDK](https://docs.getunleash.io/reference/sdks/ios-proxy) - [JavaScript Proxy SDK](https://docs.getunleash.io/reference/sdks/javascript-browser) - [React Proxy SDK](https://docs.getunleash.io/reference/sdks/react) diff --git a/website/docs/reference/custom-activation-strategies.md b/website/docs/reference/custom-activation-strategies.md index 278a706f68..4de6a19298 100644 --- a/website/docs/reference/custom-activation-strategies.md +++ b/website/docs/reference/custom-activation-strategies.md @@ -62,6 +62,6 @@ If you have not implemented the strategy in your client SDK, the check will alwa While custom strategies are _defined_ on the Unleash server, they must be _implemented_ on the client. All official Unleash client SDKs provide a way for you to implement custom strategies. You should refer to the individual SDK's documentation for specifics, but for an example, you can have a look at the [_Node.js client implementation_ section in the _how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-a). -The exact method for implementing custom strategies will vary between SDKs, but the server SDKs follow the same patterns. For front-end client SDKs ([Android](../reference/sdks/android-proxy.md), [JavaScript](../reference/sdks/javascript-browser.md), [React](../reference/sdks/react.md), [iOS](../reference/sdks/ios-proxy.md)), the custom activation strategy must be implemented in the [Unleash Proxy](../reference/unleash-proxy.md). +The exact method for implementing custom strategies will vary between SDKs, but the server SDKs follow the same patterns. For front-end client SDKs ([Android](../reference/sdks/android-proxy.md), [JavaScript](../reference/sdks/javascript-browser.md), [React](../reference/sdks/react.md), [iOS](../reference/sdks/ios-proxy.md), [Flutter](../reference/sdks/flutter.md)), the custom activation strategy must be implemented in the [Unleash Proxy](../reference/unleash-proxy.md). When implementing a strategy in your client, you will get access to the strategy's parameters and the Unleash Context. Again, refer to your specific SDK's documentation for more details. diff --git a/website/docs/reference/sdks/flutter.md b/website/docs/reference/sdks/flutter.md new file mode 100644 index 0000000000..56b7be8917 --- /dev/null +++ b/website/docs/reference/sdks/flutter.md @@ -0,0 +1,75 @@ +--- +title: Flutter Proxy SDK +--- + +This guide shows you how to use feature toggles in a Flutter app with the [Unleash Proxy](../unleash-proxy.md) and the [Unleash front-end API](../front-end-api.md). You can also check out the source code for the [Flutter Proxy SDK](https://github.com/unleash/unleash_proxy_client_flutter) on GitHub for more details around the SDK. + +## Introduction {#introduction} + +The Flutter proxy client is a tiny Unleash client written in Dart. This client stores toggles relevant for the current user with [shared preferences library](https://pub.dev/packages/shared_preferences) and synchronizes with Unleash (the proxy _or_ the Unleash front-end API) in the background. Because toggles are stored in the user's device, the client can use them to bootstrap itself the next time the user visits the same web page. + +## How to use the Flutter Proxy SDK + +## Step 1: Install + +``` +flutter pub add unleash_proxy_client_flutter +``` + +## Step 2: Initialize the SDK + +```dart +import 'package:unleash_proxy_client_flutter/unleash_proxy_client_flutter.dart'; + +final unleash = UnleashClient( + url: Uri.parse('https://app.unleash-hosted.com/demo/api/proxy'), + clientKey: 'proxy-123', + appName: 'my-app'); + +// Use `updateContext` to set Unleash context fields. +unleash.updateContext(UnleashContext(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) contains 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 (`/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. + +### Step 3: Check if feature toggle is enabled + +```dart +unleash.isEnabled('proxy.demo'); +``` + +...or get toggle variant: + +```dart +final 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 your app when toggle state updates. + +```dart +unleash.on('update', (_) { + final myToggle = unleash.isEnabled('proxy.demo'); + //do something useful +}); +``` diff --git a/website/docs/reference/sdks/index.md b/website/docs/reference/sdks/index.md index b5e254c515..f68f3e98d6 100644 --- a/website/docs/reference/sdks/index.md +++ b/website/docs/reference/sdks/index.md @@ -27,6 +27,7 @@ Client-side SDKs can connect to the [Unleash Proxy](../unleash-proxy.md) or to t - [Android SDK](android-proxy.md) +- [Flutter Proxy SDK](flutter.md) - [iOS Proxy SDK](ios-proxy.md) - [Javascript SDK](javascript-browser.md) - [React Proxy SDK](react.md) diff --git a/website/docs/reference/sdks/javascript-browser.md b/website/docs/reference/sdks/javascript-browser.md index dd5e1199f1..469ca9b1d0 100644 --- a/website/docs/reference/sdks/javascript-browser.md +++ b/website/docs/reference/sdks/javascript-browser.md @@ -2,7 +2,7 @@ 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. +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.md). 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} @@ -44,7 +44,7 @@ To connect to an Unleash proxy, you need to have an instance of the proxy runnin ::: -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. +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) contains more info on how to configure client keys for your proxy. ### Option B: Connecting directly to Unleash diff --git a/website/docs/reference/unleash-proxy.md b/website/docs/reference/unleash-proxy.md index 43e0cbef88..850419ba0e 100644 --- a/website/docs/reference/unleash-proxy.md +++ b/website/docs/reference/unleash-proxy.md @@ -103,7 +103,7 @@ Custom activation strategies can **not** be used with the Unleash-hosted proxy a ::: -The Unleash Proxy can load [custom activation strategies](../reference/custom-activation-strategies.md) for front-end client SDKs ([Android](./sdks/android-proxy.md), [JavaScript](./sdks/javascript-browser.md), [React](./sdks/react.md), [iOS](./sdks/ios-proxy.md)). For a step-by-step guide, refer to the [_how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-b). +The Unleash Proxy can load [custom activation strategies](../reference/custom-activation-strategies.md) for front-end client SDKs ([Android](./sdks/android-proxy.md), [JavaScript](./sdks/javascript-browser.md), [React](./sdks/react.md), [iOS](./sdks/ios-proxy.md), [Flutter](./sdks/flutter.md)). For a step-by-step guide, refer to the [_how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-b). To load custom strategies, use either of these two options: diff --git a/website/sidebars.js b/website/sidebars.js index 21f7bb5286..4deb4bf081 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -250,6 +250,7 @@ module.exports = { label: 'Client-side SDKs', items: [ 'reference/sdks/android-proxy', + 'reference/sdks/flutter', 'reference/sdks/ios-proxy', 'reference/sdks/javascript-browser', 'reference/sdks/react',