Flutter实时通讯插件flutter_pubnub的使用

Flutter实时通讯插件flutter_pubnub的使用

概述

flutter_pubnub 是一个跨平台的 Flutter 插件，用于实现基于 PubNub 的实时消息应用程序。该插件由 Ingenio 开发，但并非由 PubNub 提供或支持。

特性

• 支持多客户端处理消息和状态。
• 支持身份验证密钥（Auth Key）管理。
• 支持过滤表达式。
• 提供状态和错误处理。
• 支持频道组、历史记录、推送通知等。

重要提示：

• 该插件仅支持 iOS 和 Android 平台，不支持 Flutter Web。若要在 Web 或桌面平台上使用，需要 PubNub 提供纯 Dart 插件直接访问其低级 REST API。

功能路线图

当前插件已支持大部分复杂实时消息应用的需求，但仍有一些功能未覆盖，例如：

• cipher key
• custom origin

快速开始

插件尽可能遵循 PubNub 在 iOS 和 Android SDK 中的命名约定。

注意：版本 0.2.0 存在一个问题，即缺少 ProGuard 规则，导致库初始化时可能会崩溃。

简单设置

首先，导入插件并创建一个 PubNub 客户端实例：

import 'package:flutter_pubnub/pubnub.dart';

// 创建 PubNub 客户端
final PubNub _client = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx'));

PubNubConfig 构造函数允许传递以下参数：

• publishKey：发布密钥。
• subscribeKey：订阅密钥。
• authKey：身份验证密钥（可选）。
• presenceTimeout：在线状态超时时间（秒，可选）。
• uuid：用户唯一标识符（可选，默认生成）。
• filter：过滤表达式（可选）。

创建一个或多个客户端

可以为不同的 PubNub 配置创建多个客户端。

// 使用发布和订阅密钥创建客户端
final PubNub _client1 = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx'));
final PubNub _client2 = PubNub(PubNubConfig('pub-c-yyyy', 'sub-cyyy'));

// 使用身份验证密钥创建客户端
final PubNub _clientWithAuth = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx', authKey: 'auth-xxxx'));

// 使用 UUID 创建客户端
final PubNub _clientWithUUID = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx', uuid: '127c1ab5-fc7f-4c46-8460-3207b6782007'));

// 设置在线状态超时时间
final PubNub _clientWithPresenceTimeout = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx', presenceTimeout: 120));

// 设置过滤表达式
final PubNub _clientWithFilter = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx', filter: 'uuid != "127c1ab5-fc7f-4c46-8460-3207b6782007"'));

// 发布带元数据的消息
_clientWithFilter.publish(['Test-Channel1'], {'message': 'Hello World'},
    metadata: {
      'uuid': '127c1ab5-fc7f-4c46-8460-3207b6782007'
    }
);

获取客户端 UUID

有时需要获取自动分配的 UUID：

_client.uuid().then((uuid) => print('UUID: $uuid'));

订阅与取消订阅频道

一个客户端可以订阅一个或多个频道，并且可以取消订阅特定频道或所有频道。

// 订阅频道
_client.subscribe(['Test-Channel1', 'Test-Channel2']);

// 取消订阅特定频道
_client.unsubscribe(['Test-Channel1']);

// 取消订阅所有频道
_client.unsubscribeAll();

发布到频道

客户端可以向一个或多个频道发送消息。

_client.publish(['Test-Channel1'], {'message': 'Hello World!'});

如果设置了过滤器，需要在发布时传递相关元数据：

_client.publish(['Test-Channel1'], {'message': 'Hello World'},
    metadata: {
      'uuid': '127c1ab5-fc7f-4c46-8460-3207b6782007'
    }
);

处理在线状态事件

可以监听在线状态事件（如用户上线、离线等）。

_client.onStatusReceived.listen((status) => print('Status: ${status.toString()}'));

订阅 PubNub 事件

订阅消息、在线状态、错误等事件。

_client.onPresenceReceived.listen((presence) => print('Presence: ${presence.toString()}'));
_client.onMessageReceived.listen((message) => print('Message: $message'));
_client.onErrorReceived.listen((error) => print('Error: $error'));

渠道组操作

支持添加、移除、删除渠道组，以及订阅和取消订阅渠道组。

// 添加频道到渠道组
_client.addChannelsToChannelGroup('Group1', ['Channel', 'Channel2']);

// 列出渠道组中的频道
_client.listChannelsForChannelGroup('Group1').then((channels) {
  print("Channels in Group 1: $channels");
});

// 移除频道从渠道组
_client.removeChannelsFromChannelGroup('Group1', ['Channel']);

// 删除渠道组
_client.deleteChannelGroup('Group1');

// 订阅渠道组
_client.subscribeToChannelGroups(['Group1']);

// 取消订阅渠道组
_client.unsubscribeFromChannelGroups(['Group1']);

获取历史记录

可以从指定频道获取历史记录。

_client.history('Channel', 1).then((items) {
  if (items != null && items.isNotEmpty) {
    print("Last Item: $items");
  } else {
    print('No items');
  }
});

推送通知

支持通过 Firebase 发送推送通知。

_firebaseMessaging.getToken().then((token) {
  print("Token: $token");
  _client.addPushNotificationsOnChannels(PushType.FCM, token, ['Channel']);
});

列出和移除推送通知频道：

_client.listPushNotificationChannels(PushType.FCM, token).then((channels) {
  print("Push Notes Channels: $channels");
});

_client.removePushNotificationsFromChannels(PushType.FCM, token, ['Channel']);

信号

信号允许高效传输小数据包（最多 30 字节）。

_client.signal(['Channel2'], {'signal': 'Hello Signal'});

清理资源

完成操作后清理客户端资源。

_client.dispose();

示例代码

以下是一个完整的示例代码，展示如何使用 flutter_pubnub 实现基本的实时通信功能：

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:flutter_pubnub/pubnub.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: PubNubExample(),
    );
  }
}

class PubNubExample extends StatefulWidget {
  [@override](/user/override)
  _PubNubExampleState createState() => _PubNubExampleState();
}

class _PubNubExampleState extends State<PubNubExample> {
  final _client = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx'));

  [@override](/user/override)
  void initState() {
    super.initState();
    _client.onMessageReceived.listen((message) {
      print('Received Message: $message');
    });
    _client.onStatusReceived.listen((status) {
      print('Status: ${status.toString()}');
    });
  }

  [@override](/user/override)
  void dispose() {
    _client.dispose();
    super.dispose();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('PubNub Example')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            ElevatedButton(
              onPressed: () {
                _client.publish(['test-channel'], {'message': 'Hello World'});
              },
              child: Text('Send Message'),
            ),
            ElevatedButton(
              onPressed: () {
                _client.subscribe(['test-channel']);
              },
              child: Text('Subscribe'),
            ),
            ElevatedButton(
              onPressed: () {
                _client.unsubscribe(['test-channel']);
              },
              child: Text('Unsubscribe'),
            ),
          ],
        ),
      ),
    );
  }
}