Flutter Web3交互插件web3mq的使用

快速开始

要求

• Dart SDK: “>=2.18.5 <4.0.0”
• 需要一个 Web3MQ API 密钥

添加依赖

在项目的 pubspec.yaml 文件中添加以下依赖项，使用最新版本：

dependencies:
  web3mq: 0.1.2

然后运行以下命令以获取依赖项：

flutter packages get

示例项目

在项目的 example 文件夹中有一个详细的 Flutter 示例项目。你可以直接运行并进行测试。

设置API客户端

首先，你需要实例化一个聊天客户端。该客户端将管理 API 调用、事件处理，并维护与 Web3MQ 服务器的 WebSocket 连接。你应该只创建一次客户端并在整个应用程序中重用它。

final client = Web3MQClient("api-key");

日志记录

默认情况下，聊天客户端会将所有级别为 Warn 或 Error 的消息写入到标准输出。

修改日志级别

在开发过程中，你可能希望启用更多日志信息。可以通过在构造客户端时更改默认的日志级别来实现。

final client = Web3MQClient("api-key", logLevel: Level.INFO);

自定义日志处理器

你可以直接处理日志消息，而不是让它们写入到 stdout。如果你使用错误跟踪工具或希望将日志集中到一个设施中，这非常方便。

myLogHandlerFunction = (LogRecord record) {
  // 对记录执行某些操作（例如，将其发送到 Sentry 或 Fabric）
};

final client = Web3MQClient("api-key", logHandlerFunction: myLogHandlerFunction);

钱包连接器

SDK 提供的一些方法需要钱包签名，因此在调用这些方法之前应设置 WalletConnector。

client.walletConnector = walletConnector;

钱包连接器接口定义如下：

abstract class WalletConnector {
  /// 获取个人签名。
  Future<String> personalSign(String message, String address, {String? password});

  /// 连接钱包并获取用户钱包信息。
  Future<Wallet> connectWallet();
}

abstract class Wallet {
  /// accountId 支持 CAIP-10
  final List<String> accounts;

  Wallet(this.accounts);
}

离线存储

为了添加数据持久性，可以扩展 PersistenceClient 类并将其实例传递给 ChatClient。Web3MQPersistenceClient 是默认实现。

client.persistenceClient = Web3MQPersistenceClient();

注册

对于任何首次使用 Web3MQ 网络的用户，您需要在 Web3MQ 网络上注册。

此方法需要钱包签名，请确保已经设置了 WalletConnector。RegisterResponse 包含您的 PrivateKey 和 UserId。

// 将私钥保存在一个安全的地方！
final registerResponse = await client.register(did, password);

获取私钥

任何时候，您都可以通过此方法检索自己的 PrivateKey。

// 将私钥保存在一个安全的地方！
final privateKeyHex = await client.retrievePrivateKey(did, password);

连接

获取用户

通过 DID 和密码获取用户，同时指定过期时间。

final user = await client.user(did, password, expiredDuration);

或者如果已有 PrivateKey：

final user = await client.user(did, privateKeyHex, expiredDuration);

您可以持久化 user 以便下次连接。

使用用户连接

现在可以使用 User 连接到 Web3MQ。

await client.connectUser(user);

监听 wsConnectionStatusStream 以跟踪连接状态：

client.wsConnectionStatusStream.listen((event) { 
  // 处理事件 
});

通知

订阅

通过 topicId 订阅主题，然后可以从该主题接收通知。

client.subscribeTopic(topicId);

接收通知

您可以使用以下方法从 Web3MQ 服务器订阅通知。

client.notificationStream.listen((notifications) {
  // 处理通知。
});

读取状态

可能需要另一方知道您是否已阅读通知。

client.markNotificationsRead(notificationsIds);

查询

可以通过类型和分页查询所有历史通知。

Page<Notification> res = await client.queryNotifications(type, pagination);

聊天

频道列表

为了跟踪频道列表，监听 <code>channelsStream</code> 事件：

client.state.channelsStream.listen((event) {
  // 处理频道列表
});

发送消息

要发送文本消息，请调用带有消息文本和主题 ID 的 <code>sendText</code> 方法。

client.sendText('hello, world!', topicId);

消息发送状态

要接收有关消息发送状态的更新，请监听 <code>messageUpdated</code> 事件：

client.on(EventType.messageUpdated).listen((event) {
  // 处理消息状态更新
  final status = event.messageStatusResponse;
});

接收新消息

要接收新消息，请监听 <code>newMessageStream</code> 事件：

client.newMessageStream.listen((message) {
  // 处理新消息
});

查询消息列表

要查询消息列表，请调用带有主题 ID 和分页对象的 <code>queryMessagesByTopic</code> 方法。

client.queryMessagesByTopic('topicId', pagination);

创建线程

要创建线程，请调用带有原始消息 ID、主题 ID 和线程名称的 <code>createThreadByMessage</code> 方法。

client.createThreadByMessage(messageId, 'topicId', 'threadName');

线程列表

要通过给定的主题查询线程列表。

final list = await client.threadListByTopic('topicId');

示例代码

以下是完整的示例代码：

import 'package:web3mq/web3mq.dart';

Future<void> main() async {
  final client = Web3MQClient('api-key');

  final user = User("userId", DID("type", "value"), "sessionKey");
  await client.connectUser(user);

  client.notificationStream.listen((event) {
    // 处理通知
  });

  // 发送消息
  client.sendText('text', 'topic');

  client.newMessageStream.listen((event) {
    // 处理新消息
  });
}