Flutter代理客户端插件unleash_proxy_client_flutter的使用

Unleash Proxy Client for Flutter (Dart)

这是一个轻量级的Unleash客户端SDK，可以与Unleash前端API或Unleash代理或Unleash Edge一起使用。这使得任何Flutter应用程序使用Unleash变得非常简单。

如何将客户端作为模块使用

Step 1: 安装

flutter pub add unleash_proxy_client_flutter

Step 2: 初始化SDK

💡 提示：作为一个客户端SDK，此SDK需要连接到Unleash代理或Unleash前端API。有关更多信息，请参阅连接选项部分。

配置客户端以满足您的需求。以下示例仅提供所需的选项。请参考可用选项部分以获取完整列表。

import 'package:unleash_proxy_client_flutter/unleash_proxy_client_flutter.dart';

final unleash = UnleashClient(
    url: Uri.parse('https://<your-unleash-instance>/api/frontend'),
    clientKey: '<your-client-side-token>',
    appName: 'my-app');
unleash.start();

连接选项

要将此SDK连接到您的Unleash实例的前端API，请使用您的Unleash实例的前端API URL（<unleash-url>/api/frontend）作为url参数。对于clientKey参数，请使用从您的Unleash实例生成的FRONTEND令牌。有关必要步骤，请参阅如何创建API令牌指南。

要将此SDK连接到Unleash代理，请使用代理的URL和代理客户端密钥。Unleash代理文档中的配置部分包含有关如何为您的代理配置客户端密钥的更多信息。

Step 3: 让客户端同步

您应该等待客户端的ready或initialized事件，然后再开始使用它。在客户端准备好之前，它可能无法正确报告功能的状态。

unleash.on('ready', (_) {
    if (unleash.isEnabled('proxy.demo')) {
      print('proxy.demo is enabled');
    } else {
      print('proxy.demo is disabled');
    }
});

Step 4: 检查功能切换状态

一旦客户端准备就绪，你就可以开始检查应用程序中的功能。使用isEnabled方法来检查你想要的功能的状态：

unleash.isEnabled('proxy.demo');

你可以使用getVariant方法来获取一个已启用功能的变体。如果功能被禁用或没有变体，那么你会得到禁用变体。

final variant = unleash.getVariant('proxy.demo');

if (variant.name == 'blue') {
 // something with variant blue...
}

你还可以访问与变体关联的有效负载：

final variant = unleash.getVariant('proxy.demo');
final payload = variant.payload;

if (payload != null) {
  // do something with the payload
  // print(payload "${payload.type} ${payload.value}");
}

更新Unleash上下文

Unleash上下文用于根据当前用户的属性评估功能。要更新和配置此SDK中的Unleash上下文，请使用updateContext、setContextField和setContextFields方法。

// 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');

// Used to update multiple context fields on the Unleash Context.
unleash.setContextFields({'userId': '4141'});

可用选项

通过事件发射器监听更新

客户端也是一个事件发射器。这意味着你的代码可以订阅来自客户端的更新。这是当切换状态更新时更新应用程序的一种巧妙方式。

unleash.on('update', (_) {
    final myToggle = unleash.isEnabled('proxy.demo');
    //do something useful
});

可用事件：

• error - 当初始化时发生错误，或当获取函数失败，或当获取接收非OK响应对象时发出。错误对象作为有效负载发送。
• initialized - 在SDK读取存储提供商中的本地缓存数据后发出。
• ready - 在SDK成功启动并执行对Unleash代理的初始获取后发出。
• update - 每当Unleash代理返回新的特性切换配置时发出。SDK将在SDK的初始获取期间发出此事件。

注意！请记住，你应该始终在调用unleash.start()之前注册你的事件监听器。如果你在启动SDK之后注册它们，你可能会丢失重要的事件。

SessionId - 重要说明！

你可以通过"上下文"提供自定义会话ID。如果你不提供会话ID，此SDK将创建一个随机的会话ID，并将其存储在提供的存储中。通过始终拥有一个一致的会话ID，可以确保即使是“匿名”用户在评估特性切换时也能获得一致的体验，结合逐步（基于百分比）推出。

停止SDK

你可以通过调用stop方法停止Unleash客户端。一旦客户端被停止，它将不再检查更新或向服务器发送指标。

unleash.stop();

引导加载

现在可以在不需要进行API调用的情况下，使用自己的特性切换配置引导加载SDK。

这也适用于当你需要在初始化SDK后立即使切换处于某种状态时。

如何使用？

在创建新的UnleashClient时添加一个bootstrap属性。

还有一个bootstrapOverride属性，默认为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'))
});

注意事项 ⚠️

• 如果bootstrapOverride为true（默认），任何本地缓存的数据都将被引导加载指定的内容覆盖。
• 如果bootstrapOverride为false，任何本地缓存的数据都不会被覆盖，除非本地缓存为空。

管理自己的刷新机制

你可以通过将refreshInterval和/或metricsInterval选项设置为0来选择退出Unleash特性标志自动刷新机制和指标更新。 在这种情况下，调用updateToggles和/或sendMetrics方法的责任由你自己承担。

实验性：启动时不获取切换

如果你启动多个共享相同存储提供商（例如默认的SharedPreferencesStorageProvider）的客户端，你可能希望只对其中一个客户端之外的所有客户端跳过启动时获取切换。 这可以通过将experimental.togglesStorageTTL设置为非零值来实现。 例如，在下面的例子中，切换在60秒内被视为有效，并且如果它们已经存在于存储中，则不会在启动时获取。 我们建议将experimental.togglesStorageTTL设置为大于refreshInterval的值。

final anotherUnleash = UnleashClient(
    // ...
    experimental: const ExperimentalConfig(togglesStorageTTL: 60)
);

示例Demo

以下是使用unleash_proxy_client_flutter插件的一个完整示例应用，展示了如何在Flutter应用程序中集成和使用该插件。

import 'package:flutter/material.dart';
import 'package:unleash_proxy_client_flutter/unleash_proxy_client_flutter.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Unleash Integration Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(title: 'Flutter Unleash Integration Demo'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;
  bool _counterEnabled = false;

  @override
  void initState() {
    super.initState();
    var unleash = UnleashClient(
        url: Uri.parse('https://sandbox.getunleash.io/enterprise/api/frontend'),
        clientKey: 'SDKIntegration:development.f0474f4a37e60794ee8fb00a4c112de58befde962af6d5055b383ea3',
        refreshInterval: 30,
        appName: 'example-flutter-app');
    void updateCounterEnabled(_) {
      final counterEnabled = unleash.isEnabled('counter');
      setState(() {
        _counterEnabled = counterEnabled;
      });
    }
    unleash.on('ready', updateCounterEnabled);
    unleash.on('update', updateCounterEnabled);
    unleash.start();
  }

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('${widget.title} (counter is ${_counterEnabled ? 'enabled' : 'disabled'})'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline4,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _counterEnabled ? _incrementCounter : null,
        tooltip: 'Increment',
        child: _counterEnabled ? const Icon(Icons.add) : const Icon(Icons.disabled_by_default),
      ),
    );
  }
}

这个示例演示了如何使用unleash_proxy_client_flutter插件在Flutter应用程序中集成Unleash特性切换。应用程序会根据特性切换的状态启用或禁用计数器按钮，并在特性切换启用时递增计数器。