6cd938cfbc
- 实现了Android SDK的完整IM功能接口，包括消息、群组、好友、会话等核心功能 - 添加了消息收发、历史记录、撤回编辑等完整的消息操作能力 - 实现了群组管理功能，包括创建、成员管理、权限设置等操作 - 添加了好友关系链管理，支持添加、删除、分组等操作 - 实现了会话管理功能，包括置顶、免打扰、已读状态等 - 添加了黑名单、资料管理、搜索等辅助功能 - 补齐了批量操作接口，提升客户端操作效率 - 实现了WebSocket连接管理和事件监听机制 - 添加了离线消息同步和状态管理功能
334 行
6.7 KiB
Markdown
334 行
6.7 KiB
Markdown
# Flutter SDK 概览
|
||
|
||
**包名**：`xuqm_flutter_sdk` · **版本**：0.2.x · **语言**：Dart
|
||
|
||
`xuqm_flutter_sdk` 是 XuqmGroup 的 Flutter 端统一入口，通过 MethodChannel 桥接原生能力，同时提供纯 Dart 实现的 IM HTTP API。
|
||
|
||
---
|
||
|
||
## 功能模块
|
||
|
||
| 模块 | 包 | 功能 |
|
||
|------|-----|------|
|
||
| `xuqm_flutter_common` | `packages/common` | 初始化、网络、配置管理 |
|
||
| `xuqm_flutter_im` | `packages/im` | 单聊、群聊、消息收发、会话、好友、群组 |
|
||
| `xuqm_flutter_push` | `packages/push` | 设备 Token 注册、厂商检测（Android）/ APNs（iOS）|
|
||
| `xuqm_flutter_update` | `packages/update` | App 版本检查、商店跳转、APK 下载（Android）|
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
在 `pubspec.yaml` 中添加：
|
||
|
||
```yaml
|
||
dependencies:
|
||
xuqm_flutter_sdk: ^0.2.0
|
||
```
|
||
|
||
配置私有仓库（如有）：
|
||
|
||
```yaml
|
||
dependency_overrides:
|
||
xuqm_flutter_common:
|
||
hosted:
|
||
name: xuqm_flutter_common
|
||
url: https://nexus.xuqinmin.com/repository/pub-hosted/
|
||
version: ^0.2.0
|
||
```
|
||
|
||
执行安装：
|
||
|
||
```bash
|
||
flutter pub get
|
||
```
|
||
|
||
---
|
||
|
||
## 快速接入
|
||
|
||
### 1. 初始化
|
||
|
||
```dart
|
||
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';
|
||
|
||
await XuqmSDK.initialize(XuqmInitOptions(
|
||
appKey: 'your_app_key', // 在租户平台创建应用后获得
|
||
debug: true, // 可选，开启详细日志
|
||
));
|
||
```
|
||
|
||
初始化时会自动向服务端请求远程配置（IM API 地址等），若网络异常则回退到内置默认值。
|
||
|
||
如需同步初始化（不拉取远程配置）：
|
||
|
||
```dart
|
||
XuqmSDK.init(XuqmInitOptions(appKey: 'your_app_key'));
|
||
```
|
||
|
||
---
|
||
|
||
### 2. IM 登录
|
||
|
||
```dart
|
||
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';
|
||
|
||
// 只需要 userId + userSig
|
||
await XuqmImSdk().login('user_001', 'your_user_sig_jwt');
|
||
```
|
||
|
||
登录成功后会自动建立 WebSocket 连接。
|
||
|
||
---
|
||
|
||
### 3. 监听消息
|
||
|
||
```dart
|
||
final im = XuqmImSdk();
|
||
|
||
im.ws.onConnected = () {
|
||
print('WebSocket 已连接');
|
||
};
|
||
|
||
im.ws.onMessage = (XuqmImMessage msg) {
|
||
print('收到消息: ${msg.msgType} - ${msg.content}');
|
||
};
|
||
|
||
im.ws.onDisconnected = (String? reason) {
|
||
print('WebSocket 断开: $reason');
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 发送消息
|
||
|
||
```dart
|
||
// 发送文本消息
|
||
final msg = await im.sendTextMessage(
|
||
'user_002',
|
||
'SINGLE',
|
||
'Hello from Flutter!',
|
||
);
|
||
|
||
// 发送图片消息
|
||
final imgMsg = await im.sendMessage(
|
||
'user_002',
|
||
'SINGLE',
|
||
'IMAGE',
|
||
jsonEncode({'url': 'https://cdn.example.com/img.jpg', 'width': 800, 'height': 600}),
|
||
);
|
||
|
||
// 撤回消息
|
||
await im.revokeMessage(msg.id);
|
||
|
||
// 编辑消息
|
||
await im.editMessage(msg.id, '新内容');
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 会话管理
|
||
|
||
```dart
|
||
// 会话列表
|
||
final conversations = await im.listConversations();
|
||
|
||
// 置顶会话
|
||
await im.setConversationPinned('user_002', 'SINGLE', true);
|
||
|
||
// 免打扰
|
||
await im.setConversationMuted('group_xxx', 'GROUP', true);
|
||
|
||
// 标记已读
|
||
await im.markRead('user_002');
|
||
|
||
// 设置草稿
|
||
await im.setDraft('user_002', 'SINGLE', '未完成的消息');
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 好友与群组
|
||
|
||
```dart
|
||
// 好友列表
|
||
final friends = await im.listFriends();
|
||
|
||
// 添加好友
|
||
await im.addFriend('user_002');
|
||
|
||
// 移除好友
|
||
await im.removeFriend('user_002');
|
||
|
||
// 创建群组
|
||
final group = await im.createGroup('Flutter 群', ['user_001', 'user_002']);
|
||
|
||
// 群组列表
|
||
final groups = await im.listGroups();
|
||
|
||
// 添加群成员
|
||
await im.addGroupMember(group.id, 'user_003');
|
||
|
||
// 退出群聊
|
||
await im.leaveGroup(group.id);
|
||
```
|
||
|
||
---
|
||
|
||
### 7. 历史消息
|
||
|
||
```dart
|
||
// 单聊历史
|
||
final history = await im.fetchHistory('user_002', page: 0, size: 20);
|
||
|
||
// 群聊历史
|
||
final groupHistory = await im.fetchGroupHistory('group_xxx', page: 0, size: 50);
|
||
|
||
// 定位消息所在页
|
||
final page = await im.locateHistoryPage(
|
||
'user_002',
|
||
messageId: 'msg_xxx',
|
||
pageSize: 20,
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## Push 接入
|
||
|
||
```dart
|
||
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';
|
||
|
||
// 检测当前设备推送厂商（Android）
|
||
final vendor = await XuqmPushSdk.detectVendor();
|
||
// 返回：HUAWEI / XIAOMI / OPPO / VIVO / HONOR / FCM / APNS
|
||
|
||
// 请求原生推送注册
|
||
await XuqmPushSdk.requestNativeRegistration();
|
||
|
||
// 监听原生 Token 回调
|
||
XuqmPushSdk.onPushToken.listen((tokenInfo) {
|
||
final token = tokenInfo['token'];
|
||
final vendor = tokenInfo['vendor'];
|
||
print('收到 Push Token: $token, 厂商: $vendor');
|
||
|
||
// 手动上报到服务端（如需要）
|
||
final pushSdk = XuqmPushSdk();
|
||
await pushSdk.registerToken(
|
||
'user_001',
|
||
token!,
|
||
vendor: vendor,
|
||
platform: 'ANDROID',
|
||
);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## Update 接入
|
||
|
||
```dart
|
||
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';
|
||
|
||
final updateSdk = XuqmUpdateSdk();
|
||
|
||
// 检查 App 更新
|
||
final update = await updateSdk.checkAppUpdate();
|
||
if (update.needsUpdate) {
|
||
print('新版本: ${update.versionName}');
|
||
print('更新日志: ${update.changeLog}');
|
||
|
||
if (update.forceUpdate) {
|
||
// 强制更新
|
||
showForceUpdateDialog(update);
|
||
} else {
|
||
// 可选更新
|
||
showOptionalUpdateDialog(update);
|
||
}
|
||
}
|
||
|
||
// 打开商店 / 应用市场
|
||
await updateSdk.openStore(update);
|
||
|
||
// Android：直接打开 APK 下载链接
|
||
await updateSdk.openDownloadUrl(update);
|
||
```
|
||
|
||
开发/测试环境可覆盖版本号：
|
||
|
||
```dart
|
||
XuqmUpdateSdk.devSetAppVersion(100, '1.0.0');
|
||
```
|
||
|
||
---
|
||
|
||
## 多模块统一登录
|
||
|
||
无论集成了哪些模块（IM、Push、Update），**初始化和登录永远只做一次**：
|
||
|
||
```dart
|
||
// 初始化
|
||
await XuqmSDK.initialize(XuqmInitOptions(appKey: 'your_app_key'));
|
||
|
||
// 登录（业务登录成功后调用一次）
|
||
await XuqmImSdk().login('user_001', 'your_user_sig_jwt');
|
||
|
||
// 登出
|
||
await XuqmImSdk().logout();
|
||
```
|
||
|
||
---
|
||
|
||
## 完整示例
|
||
|
||
```dart
|
||
import 'dart:convert';
|
||
import 'package:flutter/material.dart';
|
||
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';
|
||
|
||
class ChatPage extends StatefulWidget {
|
||
@override
|
||
_ChatPageState createState() => _ChatPageState();
|
||
}
|
||
|
||
class _ChatPageState extends State<ChatPage> {
|
||
final im = XuqmImSdk();
|
||
final List<XuqmImMessage> messages = [];
|
||
|
||
@override
|
||
void initState() {
|
||
super.initState();
|
||
_init();
|
||
}
|
||
|
||
Future<void> _init() async {
|
||
await XuqmSDK.initialize(XuqmInitOptions(appKey: 'your_app_key'));
|
||
await im.login('user_001', 'your_user_sig_jwt');
|
||
|
||
im.ws.onMessage = (msg) {
|
||
setState(() => messages.add(msg));
|
||
};
|
||
}
|
||
|
||
Future<void> _send(String text) async {
|
||
final msg = await im.sendTextMessage('user_002', 'SINGLE', text);
|
||
setState(() => messages.add(msg));
|
||
}
|
||
|
||
@override
|
||
Widget build(BuildContext context) {
|
||
return Scaffold(
|
||
appBar: AppBar(title: Text('Flutter IM')),
|
||
body: ListView.builder(
|
||
itemCount: messages.length,
|
||
itemBuilder: (context, index) {
|
||
final msg = messages[index];
|
||
return ListTile(title: Text('${msg.fromId}: ${msg.content}'));
|
||
},
|
||
),
|
||
);
|
||
}
|
||
}
|
||
```
|
