This is a tiny Unleash Client SDK you can use together with the Unleash Proxy. This makes it super simple to use Unleash from any Flutter app.
Step 1: Unleash Proxy
Before you can use this Unleash SDK you need set up a Unleash Proxy instance. Read more about the Unleash Proxy.
Step 2: Install
flutter pub add unleash_proxy_client_flutter
Step 3: 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.
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');Step 4: Listen for when the client is ready
You shouldn't start working with the client immediately. It's recommended to wait for ready or initialized event:
unleash.on('ready', (_) {
if (unleash.isEnabled('proxy.demo')) {
print('proxy.demo is enabled');
} else {
print('proxy.demo is disabled');
}
});The difference between the events is explained below.
Step 5: Start polling the Unleash Proxy
// Used to set the context fields, shared with the Unleash Proxy. This
// method will replace the entire (mutable part) of the Unleash Context.
unleash.updateContext(UnleashContext(userId: '1233'));
// Used to update a single field on the Unleash Context.
unleash.setContextField('userId', '4141');
// Send the initial fetch towards the Unleash Proxy and starts the background polling
unleash.start();Step 6: Get toggle variant
final variant = unleash.getVariant('proxy.demo');
if(variant.name == 'blue') {
// something with variant blue...
}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. |
| 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 | 30 | How often, in seconds, the SDK should send usage metrics back to Unleash Proxy |
| disableMetrics | no | false | Set this option to true if you want to disable usage metrics |
| storageProvider | no | InMemoryStorageProvider |
Allows you to inject a custom storeProvider |
| 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 |
Provides possiblity to specify custom header that is passed to Unleash / Unleash Proxy with the clientKey |
| 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. |
| 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. |
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.
unleash.on('update', (_) {
final myToggle = unleash.isEnabled('proxy.demo');
//do something useful
});- 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 towards the Unleash Proxy.
- 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.
PS! Please remember that you should always register your event listeners before your call
unleash.start(). If you register them after you have started the SDK you risk loosing important events.
You may provide a custom session id via the "context". If you do not provide a sessionId this SDK will create a random session id, which will also be stored in the provided storage. By always having a consistent sessionId available ensures that even "anonymous" users will get a consistent experience when feature toggles is evaluated, in combination with a gradual (percentage based) rollout.
You can stop the Unleash client by calling the stop method. Once the client has been stopped, it will no longer check for updates or send metrics to the server.
A stopped client can be restarted.
unleash.stop();Now it is possible to bootstrap the SDK with your own feature toggle configuration when you don't want to make an API call.
This is also useful if you require the toggles to be in a certain state immediately after initializing the SDK.
Add a bootstrap attribute when create a new UnleashClient.
There's also a bootstrapOverride attribute which is by default is true.
final unleash = UnleashClient(
url: Uri.parse('https://app.unleash-hosted.com/demo/api/proxy'),
clientKey: 'proxy-123',
appName: 'my-app',
bootstrapOverride: false,
bootstrap: {
'demoApp.step4': ToggleConfig(
enabled: true,
impressionData: false,
variant: Variant(enabled: true, name: 'blue'))
});NOTES:
- If
bootstrapOverrideistrue(by default), any local cached data will be overridden with the bootstrap specified. - If
bootstrapOverrideisfalseany local cached data will not be overridden unless the local cache is empty.
flutter testflutter format lib testflutter analyze lib testdart pub publish