unleash_proxy 0.3.4

Unleash Flutter Proxy SDK. Unleash is an open-source feature flag service.

Unleash Flutter Proxy SDK

This library is meant to be used with the 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 💻

❗ In order to start using Unleash you must have the Flutter SDK installed on your machine.

Add unleash_proxy to your pubspec.yaml:

dependencies:
  unleash_proxy:

Install it:

flutter packages get

---

Usage

Initialize Unleash Proxy

Unleash context and configuration is required for initialize unleash app.

Context

The important properties to configure on the context are:

• appName - In case you use strategies that depend on which app
• userId - GradualRolloutStrategies often use this to decide stickiness when assigning which group of users the user end up in
• sessionId - GradualRolloutStrategies often use this to decide stickiness
• properties - In case you use custom strategies

Example:

UnleashContext(
  appName: 'APP_NAME',
  userId: 'USER_ID',
  sessionId: 'SESSION_ID',
  properties: {'variant': 'ios'},
);

Update current context:

class UnleashScreen extends StatelessWidget {
  UnleashScreen({required this.unleash});
  final UnleashApp unleash;
  
  /// [updateContext] method will update current context
  Future<void> updateContext() async {
    await unleashApp.setContext(UnleashContext(
      properties: {'variant': 'ios'},
      userId: 'exampleId',
    ));
  }
}

Configuration

For the config you must set two variables, and if you'd like to be notified when the polling thread has found updates you should also configure pollMode:

• proxyUrl - Where your proxy installation is located, for Unleash-Hosted's demo instance this is at https://app.unleash-hosted.com/demo/proxy but yours will be somewhere else
• clientKey - The api key for accessing your proxy. (renamed from clientSecret in v0.4.0)
• pollMode - See PollingModes
• bootstrap - Allows you to bootstrap the cached feature toggle configuration by using json format or List<UnleashToggle>
• onFetched - Run a function every toggle fetched from server

Example:

UnleashOptions(
  proxyUrl: 'https://UNLEASH_URL/proxy',
  clientKey: 'CLIENT_KEY',
  poolMode: UnleashPollingMode.custom(const Duration(seconds: 5)),
  bootstrap: UnleashBootstrap(
    source: [
      UnleashToggle(
        enabled: true,
        name: 'testing-source',
        variant: UnleashToggleVariant(name: 'disabled', enabled: false),
      ),
    ],
    json: source,
  ),
  onFetched: (List<UnleashToggle> toggles) {
    debugPrint('Yay! ${toggles.length} toggles fetched.');
  },
)

PollingModes

For updating toggles based on server, you have to set pollingMode in unleash configuration. Polling Mode will set to 15 seconds by default, but you can set to const Duration(seconds: 0) if you don't want to use toggle interval update or you can custom the interval duration by using custom polling mode.

If you want to stop polling imediatelly, you can call dispose(). Unleash will use the latest cache from your cache storage.

Initialize

To use the unleash_proxy to Flutter application, initialize unleash_proxy first. Create unleash_environment.dart file to save environment variables. You can follow the code bellow for basic environment config:

import 'package:flutter/services.dart';
import 'package:unleash_proxy/unleash_proxy.dart';

class UnleashEnvironment {
  static UnleashOptions get config => UnleashOptions(
    proxyUrl: 'https://UNLEASH_URL/proxy',
    clientKey: 'CLIENT_KEY',
  );

  static UnleashContext get context => UnleashContext();
}

class ToggleKeys {
  static String experiment = 'toggle-experiment';
}

Initialize unleash_proxy to the main file:

import 'package:example/unleash_environment.dart';
import 'package:flutter/material.dart';

/// Import package here
import 'package:unleash_proxy/unleash_proxy.dart';

Future<void> main() async {
  /// You only need to call this method if you need the binding to be
  /// initialized before calling [runApp].
  WidgetsFlutterBinding.ensureInitialized();

  /// Initialize unleash client here
  final unleashApp = await Unleash.initializeApp(
    options: await UnleashEnvironment.config,
    context: UnleashEnvironment.context,
  );

  runApp(App(app: unleashApp));
}

Use Unleash Proxy Toggle

import 'package:example/unleash_environment.dart';
import 'package:flutter/material.dart';
import 'package:unleash_proxy/unleash_proxy.dart';

class BasicUsageScreen extends StatelessWidget {
  const BasicUsageScreen({super.key, required this.app});

  final UnleashApp app;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Basic Usage'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'Toggle Status',
              style: TextStyle(height: 2.5, fontWeight: FontWeight.w500),
            ),
            toggleStatus(),
          ],
        ),
      ),
    );
  }

  Widget toggleStatus() {
    /// Call [isEnabled] to get the toggle value
    final status = app.isEnabled(ToggleKeys.experiment);

    return Text(status == true ? 'Enabled' : 'Disabled');
  }
}

Can check the example here

Continuous Integration 🤖

Unleash Flutter Proxy SDK comes with a built-in GitHub Actions workflow powered by Very Good Workflows but you can also add your preferred CI/CD solution.

Out of the box, on each pull request and push, the CI formats, lints, and tests the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses Very Good Analysis for a strict set of analysis options used by our team. Code coverage is enforced using the Very Good Workflows.

---

Running Tests 🧪

For first time users, install the very_good_cli:

dart pub global activate very_good_cli

To run all unit tests:

very_good test --coverage

To view the generated coverage report you can use lcov.

# Generate Coverage Report
genhtml coverage/lcov.info -o coverage/

# Open Coverage Report
open coverage/index.html

Issues

Please file any issues, bugs or feature requests as an issue on the GitHub page. Commercial support is available, you can contact me at [e-mail].

Author

This unleash_proxy plugin for Flutter is developed by Arif Hidayat.