feat(im): 添加即时消息SDK核心功能实现
- 实现了聊天消息发送功能，支持文本、图片、视频、音频、文件等多种消息类型 - 集成了文件上传下载功能，支持多媒体文件的传输和管理 - 添加了群组管理功能，包括创建群组、成员管理、权限控制等操作 - 实现了好友系统，支持好友添加、删除、分组等功能 - 集成了黑名单管理，提供用户屏蔽和解除屏蔽功能 - 添加了会话管理功能，支持对话列表、未读消息统计等 - 实现了历史消息查询和搜索功能 - 添加了实时连接状态管理和自动重连机制
这个提交包含在：
XuqmGroup
父节点
6cd938cfbc
当前提交
277e8ed7c6
@ -24,6 +24,7 @@ export default defineConfig({
|
||||
{ text: 'Flutter', link: '/flutter/' },
|
||||
{ text: 'HarmonyOS', link: '/harmony/' },
|
||||
{ text: '微信小程序', link: '/miniprogram/' },
|
||||
{ text: 'H5', link: '/h5/' },
|
||||
],
|
||||
},
|
||||
{ text: 'API 速查', link: '/server/api' },
|
||||
@ -78,9 +79,13 @@ export default defineConfig({
|
||||
'/miniprogram/': [
|
||||
{ text: '概览', link: '/miniprogram/' },
|
||||
],
|
||||
'/h5/': [
|
||||
{ text: '概览', link: '/h5/' },
|
||||
],
|
||||
'/server/': [
|
||||
{ text: 'API 速查', link: '/server/api' },
|
||||
{ text: 'WebSocket', link: '/server/websocket' },
|
||||
{ text: 'Go Server SDK', link: '/server/go-sdk' },
|
||||
{ text: 'Python Server SDK', link: '/server/python-sdk' },
|
||||
{ text: '错误码', link: '/server/errors' },
|
||||
],
|
||||
},
|
||||
|
||||
@ -30,7 +30,7 @@ class MyApp : Application() {
|
||||
|
||||
## 登录鉴权（UserSig）
|
||||
|
||||
`userSig` 由业务服务端用 `appSecret` 签发。登录只需 `userId + userSig`：
|
||||
`userSig` 由业务服务端签发。登录只需 `userId + userSig`：
|
||||
|
||||
```kotlin
|
||||
import androidx.lifecycle.lifecycleScope
|
||||
@ -45,7 +45,7 @@ lifecycleScope.launch {
|
||||
}
|
||||
```
|
||||
|
||||
> 登录成功后，IM 模块会自动连接 WebSocket，Push 模块会自动注册设备 Token。
|
||||
> 登录成功后，IM 模块会自动连接，Push 模块会自动注册设备 Token。
|
||||
|
||||
---
|
||||
|
||||
@ -59,7 +59,7 @@ import com.xuqm.sdk.im.listener.ImEventListener
|
||||
import com.xuqm.sdk.im.model.ImMessage
|
||||
|
||||
ImSDK.addListener(object : ImEventListener {
|
||||
override fun onConnected() { /* WebSocket 已连接 */ }
|
||||
override fun onConnected() { /* IM 已连接 */ }
|
||||
override fun onMessage(msg: ImMessage) { /* 单聊消息 */ }
|
||||
override fun onGroupMessage(msg: ImMessage) { /* 群聊消息 */ }
|
||||
override fun onRead(msg: ImMessage) { /* 对方已读回执 */ }
|
||||
@ -322,5 +322,3 @@ lifecycleScope.launch {
|
||||
| `QUOTE` | 引用 | `{quotedMsgId, quotedContent, text}` |
|
||||
| `MERGE` | 合并转发 | `{title, msgList}` |
|
||||
| `REVOKED` | 撤回 | 系统内部填充 |
|
||||
|
||||
[→ 完整 API Reference](./api)
|
||||
|
||||
@ -43,8 +43,8 @@ dependencies {
|
||||
// Application.onCreate()
|
||||
XuqmSDK.initialize(
|
||||
context = this,
|
||||
appKey = "your_app_key", // 在租户平台创建应用后获得
|
||||
logLevel = LogLevel.WARN, // 可选，DEBUG 开启详细日志
|
||||
appKey = "your_app_key",
|
||||
logLevel = LogLevel.WARN,
|
||||
)
|
||||
```
|
||||
|
||||
@ -56,13 +56,13 @@ XuqmSDK.initialize(
|
||||
lifecycleScope.launch {
|
||||
XuqmSDK.login(
|
||||
userId = "user_001",
|
||||
userSig = "your_user_sig_jwt", // 由业务服务端签发
|
||||
userSig = "your_user_sig_jwt",
|
||||
)
|
||||
}
|
||||
|
||||
// 监听实时消息
|
||||
ImSDK.addListener(object : ImEventListener {
|
||||
override fun onConnected() { /* WebSocket 已连接 */ }
|
||||
override fun onConnected() { /* IM 已连接 */ }
|
||||
override fun onMessage(msg: ImMessage) { /* 单聊消息 */ }
|
||||
override fun onGroupMessage(msg: ImMessage) { /* 群聊消息 */ }
|
||||
override fun onRead(msg: ImMessage) { /* 对方已读回执 */ }
|
||||
@ -151,7 +151,7 @@ XuqmSDK.initialize(context, appKey = "your_app_key")
|
||||
// 登录（业务登录成功后调用一次）
|
||||
XuqmSDK.login(userId = "user_001", userSig = "jwt_token")
|
||||
// ↓ 自动触发
|
||||
// · ImSDK.onSdkLogin → 连接 WebSocket
|
||||
// · ImSDK.onSdkLogin → 连接 IM
|
||||
// · PushSDK.onSdkLogin → 注册厂商 Token 并上报
|
||||
// · UpdateSDK.onSdkLogin → 无需额外操作（检查时自动携带凭证）
|
||||
|
||||
@ -160,7 +160,7 @@ XuqmSDK.logout()
|
||||
// ↓ 自动触发所有模块清理
|
||||
```
|
||||
|
||||
> **注意**：`userSig` 由业务服务端签发。若需更新登录态，请直接重新登录；如需撤销权限，可在租户平台重置 `appSecret` 或拉黑账号。
|
||||
> **注意**：`userSig` 由业务服务端签发。若需更新登录态，请直接重新登录。
|
||||
|
||||
### 8. 版本更新
|
||||
|
||||
@ -188,5 +188,3 @@ lifecycleScope.launch {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[→ 完整 API Reference](./api)
|
||||
|
||||
@ -117,3 +117,28 @@ Update 模块与 IM、Push 模块共享同一套登录态：
|
||||
XuqmSDK.login(userId = "user_001", userSig = "jwt_token")
|
||||
// UpdateSDK 在 checkAppUpdate 时自动携带 appKey，无需额外登录操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 一键打包上传
|
||||
|
||||
SDK 提供 `xuqmRelease` Gradle 任务，可一键完成 Release 构建并上传至 XuqmGroup 版本管理服务：
|
||||
|
||||
```bash
|
||||
./gradlew xuqmRelease
|
||||
```
|
||||
|
||||
任务执行流程：
|
||||
1. 执行 `assembleRelease` 构建 Release APK
|
||||
2. 自动提取版本号、versionCode、更新日志
|
||||
3. 上传 APK 到 XuqmGroup 后台
|
||||
4. 返回发布结果
|
||||
|
||||
如需自定义配置，在 `app/build.gradle.kts` 中添加：
|
||||
|
||||
```kotlin
|
||||
xuqmRelease {
|
||||
releaseNotesFile = file("CHANGELOG.md")
|
||||
forceUpdate = false
|
||||
}
|
||||
```
|
||||
|
||||
@ -19,29 +19,17 @@
|
||||
|
||||
## 安装
|
||||
|
||||
在 `pubspec.yaml` 中添加：
|
||||
SDK 通过 Gitea Git 仓库发布，在 `pubspec.yaml` 中配置：
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
xuqm_flutter_sdk: ^0.2.0
|
||||
xuqm_flutter_sdk:
|
||||
git:
|
||||
url: https://xuqinmin.com/xuqinmin12/XuqmGroup-FlutterSDK.git
|
||||
ref: v0.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
|
||||
```
|
||||
> Gitea Package Registry 暂不支持 Dart/Flutter 包格式，因此通过 Git Tag 方式发布。
|
||||
|
||||
---
|
||||
|
||||
@ -53,14 +41,13 @@ flutter pub get
|
||||
import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';
|
||||
|
||||
await XuqmSDK.initialize(XuqmInitOptions(
|
||||
appKey: 'your_app_key', // 在租户平台创建应用后获得
|
||||
debug: true, // 可选，开启详细日志
|
||||
appKey: 'your_app_key',
|
||||
debug: true,
|
||||
));
|
||||
```
|
||||
|
||||
初始化时会自动向服务端请求远程配置（IM API 地址等），若网络异常则回退到内置默认值。
|
||||
|
||||
如需同步初始化（不拉取远程配置）：
|
||||
|
||||
```dart
|
||||
XuqmSDK.init(XuqmInitOptions(appKey: 'your_app_key'));
|
||||
@ -77,7 +64,7 @@ import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart';
|
||||
await XuqmImSdk().login('user_001', 'your_user_sig_jwt');
|
||||
```
|
||||
|
||||
登录成功后会自动建立 WebSocket 连接。
|
||||
登录成功后会自动建立 IM 实时连接。
|
||||
|
||||
---
|
||||
|
||||
@ -87,7 +74,7 @@ await XuqmImSdk().login('user_001', 'your_user_sig_jwt');
|
||||
final im = XuqmImSdk();
|
||||
|
||||
im.ws.onConnected = () {
|
||||
print('WebSocket 已连接');
|
||||
print('IM 已连接');
|
||||
};
|
||||
|
||||
im.ws.onMessage = (XuqmImMessage msg) {
|
||||
@ -95,7 +82,7 @@ im.ws.onMessage = (XuqmImMessage msg) {
|
||||
};
|
||||
|
||||
im.ws.onDisconnected = (String? reason) {
|
||||
print('WebSocket 断开: $reason');
|
||||
print('IM 断开: $reason');
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
@ -18,7 +18,6 @@
|
||||
2. 填写应用名称、平台类型（Android / iOS / Web / RN / 小程序 / HarmonyOS）
|
||||
3. 创建成功后获得：
|
||||
- `appKey`（客户端使用）
|
||||
- `appSecret`（服务端使用，**不可泄露**）
|
||||
|
||||
---
|
||||
|
||||
@ -33,20 +32,17 @@ XuqmSDK.initialize(context, appKey = "your_app_key")
|
||||
|
||||
```swift
|
||||
// iOS
|
||||
let config = SDKConfig(appKey: "your_app_key", appSecret: "your_app_secret")
|
||||
XuqmSDK.shared.initialize(config: config)
|
||||
```
|
||||
|
||||
```ts
|
||||
// Vue3 / Web
|
||||
init({ appKey: 'your_app_key', appSecret: 'your_app_secret' })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 服务端签发 UserSig
|
||||
|
||||
`appSecret` 只应保存在业务服务端，用于为每个用户签发 `userSig`。
|
||||
|
||||
### 签发逻辑（示例）
|
||||
|
||||
@ -54,10 +50,8 @@ init({ appKey: 'your_app_key', appSecret: 'your_app_secret' })
|
||||
// Node.js
|
||||
import jwt from 'jsonwebtoken'
|
||||
|
||||
function generateUserSig(userId: string, appKey: string, appSecret: string): string {
|
||||
return jwt.sign(
|
||||
{ userId, appKey },
|
||||
appSecret,
|
||||
{ algorithm: 'HS256' }
|
||||
)
|
||||
}
|
||||
@ -79,12 +73,10 @@ def generate_user_sig(user_id: str, app_key: str, app_secret: str) -> str:
|
||||
// Go
|
||||
import "github.com/golang-jwt/jwt/v5"
|
||||
|
||||
func GenerateUserSig(userID, appKey, appSecret string) (string, error) {
|
||||
token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
|
||||
"userId": userID,
|
||||
"appKey": appKey,
|
||||
})
|
||||
return token.SignedString([]byte(appSecret))
|
||||
}
|
||||
```
|
||||
|
||||
@ -107,10 +99,8 @@ Response: { "userSig": "jwt_token_string" }
|
||||
客户端
|
||||
→ 业务登录（用户名/密码）
|
||||
→ 业务服务端验证成功
|
||||
→ 业务服务端调用 generateUserSig(userId, appKey, appSecret)
|
||||
→ 返回 userSig 给客户端
|
||||
→ 客户端调用 XuqmSDK.login(userId, userSig)
|
||||
→ SDK 自动连接 WebSocket
|
||||
→ 开始收发消息
|
||||
```
|
||||
|
||||
@ -129,9 +119,7 @@ Response: { "userSig": "jwt_token_string" }
|
||||
|
||||
## 安全提示
|
||||
|
||||
- `appSecret` **绝不下发到客户端**，仅用于服务端签发 UserSig
|
||||
- 若需撤销用户权限，可在租户平台重置 `appSecret` 或拉黑账号
|
||||
- 所有 API 通信使用 HTTPS / WSS
|
||||
- 所有 API 通信使用 HTTPS
|
||||
- UserSig 当前版本不过期，业务方可自行控制签发逻辑
|
||||
|
||||
[→ 快速开始 →](./quickstart)
|
||||
|
||||
@ -5,8 +5,8 @@
|
||||
## 1. 注册账号与创建应用
|
||||
|
||||
1. 访问 [XuqmGroup 控制台](https://dev.xuqinmin.com)
|
||||
2. 注册租户账号，创建应用
|
||||
3. 记录 `appKey`（Android）或 `appId + appSecret`（iOS）
|
||||
2. 注册开发者账号，创建应用
|
||||
3. 记录 `appKey`
|
||||
|
||||
## 2. 选择你的平台
|
||||
|
||||
@ -18,33 +18,18 @@
|
||||
| Vue3 / Web | [Vue3 SDK →](/vue3/) |
|
||||
| HarmonyOS | [HarmonyOS SDK →](/harmony/) |
|
||||
|
||||
## 3. 演示环境
|
||||
|
||||
所有 SDK 均可直接连接演示环境验证功能：
|
||||
|
||||
```
|
||||
API 地址：https://dev.xuqinmin.com
|
||||
WS 地址：wss://dev.xuqinmin.com/ws/im
|
||||
演示 AppKey：ak_demo_chat
|
||||
演示用户：demo_alice / demo_bob
|
||||
```
|
||||
|
||||
## 4. 演示项目
|
||||
|
||||
手机端演示包和 Web 演示入口单独放在 [演示项目](/demo/) 页面，便于直接扫码或跳转验证。
|
||||
|
||||
## 5. 接入流程
|
||||
## 3. 接入流程
|
||||
|
||||
```
|
||||
你的业务服务端
|
||||
→ 持有 appKey/appSecret
|
||||
→ 持有 appSecret
|
||||
→ 调用 IM 登录接口换取 IM Token（或签发 UserSig JWT）
|
||||
→ 平台内部协议字段由 SDK 和后端自动处理，业务方无需感知
|
||||
→ 返回 Token / UserSig 给客户端
|
||||
|
||||
客户端 SDK
|
||||
→ 使用 Token / UserSig 初始化 IM 连接
|
||||
→ 建立 WebSocket 长连接
|
||||
→ 使用 appKey 初始化
|
||||
→ 使用 Token / UserSig 登录 IM
|
||||
→ 开始收发消息
|
||||
```
|
||||
|
||||
@ -52,7 +37,7 @@ WS 地址：wss://dev.xuqinmin.com/ws/im
|
||||
|
||||
---
|
||||
|
||||
## 6. Android Demo 运行说明
|
||||
## 4. Android Demo 运行说明
|
||||
|
||||
### 环境要求
|
||||
|
||||
@ -66,7 +51,6 @@ WS 地址：wss://dev.xuqinmin.com/ws/im
|
||||
2. 等待 Gradle Sync 完成（首次可能需要下载依赖）
|
||||
3. 在 `sample-app/src/main/java/.../MainActivity.kt` 或对应配置中修改服务器地址（如需连接本地环境）
|
||||
4. 选择模拟器或真机，点击 **Run 'sample-app'**
|
||||
5. 使用演示账号登录：`user_a` / `123456` 或 `user_b` / `123456`
|
||||
|
||||
### 关键路径
|
||||
|
||||
@ -91,7 +75,7 @@ adb -s emulator-5556 logcat -d "*:S" XuqmImSDK:D XuqmImClient:D 2>/dev/null | ta
|
||||
|
||||
---
|
||||
|
||||
## 7. iOS Demo 运行说明
|
||||
## 5. iOS Demo 运行说明
|
||||
|
||||
### 环境要求
|
||||
|
||||
@ -105,7 +89,6 @@ adb -s emulator-5556 logcat -d "*:S" XuqmImSDK:D XuqmImClient:D 2>/dev/null | ta
|
||||
2. 等待 Swift Package Manager 依赖解析完成
|
||||
3. 在 Xcode 顶部选择目标模拟器（如 iPhone 16 Pro）或连接的真机
|
||||
4. 点击 **Run**（⌘+R）
|
||||
5. 使用演示账号登录验证消息收发
|
||||
|
||||
### 关键路径
|
||||
|
||||
|
||||
197
docs-site/docs/h5/index.md
普通文件
197
docs-site/docs/h5/index.md
普通文件
@ -0,0 +1,197 @@
|
||||
# H5 SDK 接入指南
|
||||
|
||||
**包名**：`@xuqm/h5-sdk` · **语言**：TypeScript / JavaScript · **格式**：ESM + UMD
|
||||
|
||||
`@xuqm/h5-sdk` 是从 Vue3 SDK 提取的纯 JavaScript/TypeScript 核心库，**不依赖任何前端框架**（Vue/React/Angular 均可使用），可在任何支持 ES6 的浏览器或 H5 环境中运行。
|
||||
|
||||
> **功能范围**：仅包含 **IM** 功能（消息收发、会话管理、好友、群组），**不包含 Push 和 Update**。
|
||||
|
||||
---
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
npm install @xuqm/h5-sdk
|
||||
```
|
||||
|
||||
或 CDN 引入：
|
||||
|
||||
```html
|
||||
<script src="https://unpkg.com/@xuqm/h5-sdk@latest/dist/index.umd.js"></script>
|
||||
<script>
|
||||
const { init, ImManager, login } = XuqmH5SDK
|
||||
</script>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速接入
|
||||
|
||||
### 1. 初始化
|
||||
|
||||
只需传入 `appKey`，服务器地址由 SDK 内置。
|
||||
|
||||
```typescript
|
||||
import { init } from '@xuqm/h5-sdk'
|
||||
|
||||
init({
|
||||
appKey: 'your_app_key', // 在租户平台创建应用后获得
|
||||
})
|
||||
```
|
||||
|
||||
### 2. 登录
|
||||
|
||||
```typescript
|
||||
import { login } from '@xuqm/h5-sdk'
|
||||
|
||||
await login('user_001', 'your_user_sig_jwt')
|
||||
```
|
||||
|
||||
### 3. IM 管理器
|
||||
|
||||
```typescript
|
||||
import { ImManager } from '@xuqm/h5-sdk'
|
||||
|
||||
const im = new ImManager()
|
||||
|
||||
// 监听连接状态
|
||||
im.on('connected', () => console.log('IM 已连接'))
|
||||
im.on('disconnected', () => console.log('IM 已断开'))
|
||||
|
||||
// 监听实时消息
|
||||
im.on('messages', (msgs) => {
|
||||
console.log('收到消息', msgs)
|
||||
})
|
||||
|
||||
// 监听会话列表变化
|
||||
im.on('conversations', (convs) => {
|
||||
console.log('会话列表更新', convs)
|
||||
})
|
||||
|
||||
// 开始连接
|
||||
im.connect()
|
||||
```
|
||||
|
||||
### 4. 发送消息
|
||||
|
||||
```typescript
|
||||
// 发送文本
|
||||
im.send({
|
||||
toId: 'user_002',
|
||||
chatType: 'SINGLE',
|
||||
msgType: 'TEXT',
|
||||
content: 'Hello H5!',
|
||||
})
|
||||
```
|
||||
|
||||
### 5. 发送文件消息（自动上传）
|
||||
|
||||
SDK 内部自动上传文件到文件服务器，无需调用方手动上传。
|
||||
|
||||
```typescript
|
||||
import { sendImageMessage, sendFileMessage } from '@xuqm/h5-sdk'
|
||||
|
||||
// 发送图片（从 input 元素获取）
|
||||
const file = document.querySelector('input[type="file"]').files[0]
|
||||
await sendImageMessage('user_002', 'SINGLE', file, 800, 600)
|
||||
|
||||
// 发送文件
|
||||
await sendFileMessage('user_002', 'SINGLE', file)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心 API
|
||||
|
||||
### 事件订阅
|
||||
|
||||
| 事件 | 回调签名 | 说明 |
|
||||
|------|---------|------|
|
||||
| `connected` | `() => void` | IM 实时连接已建立 |
|
||||
| `disconnected` | `() => void` | IM 实时连接已断开 |
|
||||
| `messages` | `(msgs: ImMessage[]) => void` | 收到新消息 |
|
||||
| `conversations` | `(convs: ConversationData[]) => void` | 会话列表变化 |
|
||||
| `error` | `(err: Error) => void` | 发生错误 |
|
||||
|
||||
```typescript
|
||||
im.on('conversations', (convs) => {
|
||||
// 更新 UI
|
||||
})
|
||||
im.off('conversations', handler) // 取消订阅
|
||||
```
|
||||
|
||||
### 状态属性
|
||||
|
||||
```typescript
|
||||
im.connected // boolean，是否已连接
|
||||
im.messages // ImMessage[]，当前消息列表
|
||||
im.conversations // ConversationData[]，当前会话列表
|
||||
im.error // Error | null，最近错误
|
||||
```
|
||||
|
||||
### HTTP API
|
||||
|
||||
所有 IM 功能均通过纯函数暴露：
|
||||
|
||||
```typescript
|
||||
import {
|
||||
sendMessage,
|
||||
sendTextMessage,
|
||||
sendImageMessage,
|
||||
sendVideoMessage,
|
||||
sendFileMessage,
|
||||
sendAudioMessage,
|
||||
fetchHistory,
|
||||
fetchGroupHistory,
|
||||
listConversations,
|
||||
markRead,
|
||||
listFriends,
|
||||
addFriend,
|
||||
listGroups,
|
||||
createGroup,
|
||||
// ...
|
||||
} from '@xuqm/h5-sdk'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 与框架集成
|
||||
|
||||
### React
|
||||
|
||||
```tsx
|
||||
import { useEffect, useState } from 'react'
|
||||
import { ImManager } from '@xuqm/h5-sdk'
|
||||
|
||||
function useIm() {
|
||||
const [im] = useState(() => new ImManager())
|
||||
const [messages, setMessages] = useState([])
|
||||
const [conversations, setConversations] = useState([])
|
||||
|
||||
useEffect(() => {
|
||||
im.on('messages', setMessages)
|
||||
im.on('conversations', setConversations)
|
||||
im.connect()
|
||||
return () => {
|
||||
im.off('messages', setMessages)
|
||||
im.off('conversations', setConversations)
|
||||
im.disconnect()
|
||||
}
|
||||
}, [im])
|
||||
|
||||
return { im, messages, conversations }
|
||||
}
|
||||
```
|
||||
|
||||
### 纯 HTML/JS
|
||||
|
||||
```html
|
||||
<script src="https://unpkg.com/@xuqm/h5-sdk@latest/dist/index.umd.js"></script>
|
||||
<script>
|
||||
XuqmH5SDK.init({ appKey: 'your_app_key' })
|
||||
XuqmH5SDK.login('user_001', 'userSig')
|
||||
const im = new XuqmH5SDK.ImManager()
|
||||
im.on('messages', function(msgs) { console.log(msgs) })
|
||||
im.connect()
|
||||
</script>
|
||||
```
|
||||
@ -15,7 +15,6 @@ import common from '@ohos.app.ability.common'
|
||||
const context = getContext(this) as common.UIAbilityContext
|
||||
await XuqmSDK.init(context, {
|
||||
appKey: 'your_app_key',
|
||||
appSecret: 'your_app_secret',
|
||||
})
|
||||
```
|
||||
|
||||
@ -190,5 +189,3 @@ await im.removeFriend('user_002')
|
||||
| `MERGE` | 合并转发 |
|
||||
| `FORWARD` | 转发 |
|
||||
| `REVOKED` | 撤回 |
|
||||
|
||||
[→ 完整 API Reference](./api)
|
||||
|
||||
@ -8,7 +8,7 @@
|
||||
|------|------|
|
||||
| `XuqmSDK` | 全局初始化 |
|
||||
| `ImSDK` | 单聊、群聊、消息收发 |
|
||||
| `UpdateSDK` | App 版本检查、RN Bundle 热更新 |
|
||||
| `UpdateSDK` | App 版本检查、整包更新 |
|
||||
|
||||
## 安装
|
||||
|
||||
@ -22,70 +22,6 @@
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Push 接入
|
||||
|
||||
HarmonyOS SDK 提供 `PushSDK` 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS 推送服务的 Token 后调用注册接口。
|
||||
|
||||
```typescript
|
||||
import { PushSDK } from '@xuqm/harmony-sdk'
|
||||
|
||||
// 注册 Push Token（在获取到系统推送 Token 后调用）
|
||||
await PushSDK.registerToken('harmony_push_token', 'user_001')
|
||||
|
||||
// 登出时注销 Token
|
||||
await PushSDK.unregisterToken('harmony_push_token')
|
||||
```
|
||||
|
||||
> HarmonyOS 推送 Token 通过系统 Push Kit 获取，具体接入请参考 HarmonyOS 官方推送文档。`vendor` 固定为 `HARMONY`，`platform` 固定为 `harmony`。
|
||||
|
||||
---
|
||||
|
||||
## 9. 版本更新
|
||||
|
||||
HarmonyOS SDK 提供整包检查和 RN Bundle 热更新能力。
|
||||
|
||||
### 9.1 检查 App 更新
|
||||
|
||||
```typescript
|
||||
import { UpdateSDK } from '@xuqm/harmony-sdk'
|
||||
|
||||
const result = await UpdateSDK.checkAppUpdate('your_app_key')
|
||||
if (result.hasUpdate) {
|
||||
console.log('发现新版本:', result.info?.latestVersionCode)
|
||||
// HarmonyOS 整包更新只提供应用市场跳转
|
||||
if (result.info?.marketUrl) {
|
||||
await UpdateSDK.openAppMarket(getContext(this), result.info.marketUrl)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 9.2 RN Bundle 热更新
|
||||
|
||||
```typescript
|
||||
const rnResult = await UpdateSDK.checkRNUpdate(
|
||||
'your_app_key',
|
||||
'home', // bundle 名称
|
||||
1 // 当前 bundle 版本号
|
||||
)
|
||||
|
||||
if (rnResult.hasUpdate) {
|
||||
console.log('发现 RN Bundle 更新:', rnResult.info?.bundleVersion)
|
||||
|
||||
// 下载 Bundle
|
||||
const destPath = await UpdateSDK.downloadRnBundle(
|
||||
getContext(this),
|
||||
rnResult.info!.downloadUrl,
|
||||
'home.bundle'
|
||||
)
|
||||
console.log('Bundle 下载完成:', destPath)
|
||||
// 缓存至本地，由 BundleRuntime 加载
|
||||
}
|
||||
```
|
||||
|
||||
> 与第 7 节「检查更新」中的示例相比，此处展示了 `UpdateSDK` 的完整独立 API。HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。
|
||||
|
||||
配置私有仓库（`.ohpmrc`）：
|
||||
|
||||
```
|
||||
@ -122,14 +58,14 @@ import { XuqmSDK, ImSDK } from '@xuqm/harmony-sdk'
|
||||
|
||||
// 只需要 userId + userSig
|
||||
await XuqmSDK.login('user_001', 'your_user_sig_jwt')
|
||||
// 如果集成了 ImSDK，XuqmSDK.login 会自动触发 WebSocket 连接
|
||||
// 如果集成了 ImSDK，XuqmSDK.login 会自动触发 IM 实时连接
|
||||
```
|
||||
|
||||
### 3. 监听消息
|
||||
|
||||
```typescript
|
||||
ImSDK.addListener({
|
||||
onConnected(): void { console.log('WS connected') },
|
||||
onConnected(): void { console.log('IM connected') },
|
||||
onDisconnected(reason: string | null): void { },
|
||||
onMessage(msg: ImMessage): void { /* 处理消息 */ },
|
||||
onError(err: string): void { },
|
||||
@ -178,15 +114,9 @@ const appInfo = await UpdateSDK.checkAppUpdate(1)
|
||||
if (appInfo?.marketUrl) {
|
||||
await UpdateSDK.openAppMarket(getContext(this), appInfo.marketUrl)
|
||||
}
|
||||
|
||||
const bundle = await UpdateSDK.checkRNUpdate('home', '1.0.0')
|
||||
if (bundle) {
|
||||
const content = await UpdateSDK.downloadBundle(bundle.downloadUrl)
|
||||
// 缓存至本地，由 BundleRuntime 加载
|
||||
}
|
||||
```
|
||||
|
||||
Harmony 的整包更新只提供应用市场跳转，不提供本地安装包下载。
|
||||
HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。
|
||||
|
||||
## ArkUI 示例
|
||||
|
||||
@ -237,7 +167,7 @@ struct ChatView {
|
||||
|
||||
## 8. Push 接入
|
||||
|
||||
HarmonyOS SDK 提供 `PushSDK` 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS 推送服务的 Token 后调用注册接口。
|
||||
HarmonyOS SDK 提供 `PushSDK` 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS PushKit 推送服务的 Token 后调用注册接口。
|
||||
|
||||
```typescript
|
||||
import { PushSDK } from '@xuqm/harmony-sdk'
|
||||
@ -255,7 +185,7 @@ await PushSDK.unregisterToken('harmony_push_token')
|
||||
|
||||
## 9. 版本更新
|
||||
|
||||
HarmonyOS SDK 提供整包检查和 RN Bundle 热更新能力。
|
||||
HarmonyOS SDK 提供整包检查能力。
|
||||
|
||||
### 9.1 检查 App 更新
|
||||
|
||||
@ -272,27 +202,4 @@ if (result.hasUpdate) {
|
||||
}
|
||||
```
|
||||
|
||||
### 9.2 RN Bundle 热更新
|
||||
|
||||
```typescript
|
||||
const rnResult = await UpdateSDK.checkRnUpdate(
|
||||
'your_app_key',
|
||||
'home', // bundle 名称
|
||||
1 // 当前 bundle 版本号
|
||||
)
|
||||
|
||||
if (rnResult.hasUpdate) {
|
||||
console.log('发现 RN Bundle 更新:', rnResult.info?.bundleVersion)
|
||||
|
||||
// 下载 Bundle
|
||||
const destPath = await UpdateSDK.downloadRnBundle(
|
||||
getContext(this),
|
||||
rnResult.info!.downloadUrl,
|
||||
'home.bundle'
|
||||
)
|
||||
console.log('Bundle 下载完成:', destPath)
|
||||
// 缓存至本地，由 BundleRuntime 加载
|
||||
}
|
||||
```
|
||||
|
||||
> 与第 7 节「检查更新」中的示例相比，此处展示了 `UpdateSDK` 的完整独立 API。HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。
|
||||
> HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。
|
||||
|
||||
@ -87,7 +87,6 @@ import common from '@ohos.app.ability.common'
|
||||
const context = getContext(this) as common.UIAbilityContext
|
||||
await XuqmSDK.init(context, {
|
||||
appKey: 'your_app_key',
|
||||
appSecret: 'your_app_secret',
|
||||
})
|
||||
```
|
||||
|
||||
|
||||
@ -38,7 +38,7 @@ features:
|
||||
link: /harmony/
|
||||
- icon: 🔌
|
||||
title: 服务端 API
|
||||
details: 完整 REST API 速查，WebSocket STOMP 协议说明
|
||||
details: 完整 REST API 速查，IM 实时连接协议说明
|
||||
link: /server/api
|
||||
- icon: 📱
|
||||
title: 演示项目
|
||||
|
||||
@ -11,7 +11,6 @@
|
||||
```swift
|
||||
import XuqmSDK
|
||||
|
||||
let config = SDKConfig(appKey: "your_app_key", appSecret: "your_app_secret")
|
||||
XuqmSDK.shared.initialize(config: config)
|
||||
```
|
||||
|
||||
@ -23,7 +22,6 @@ import XuqmSDK
|
||||
try await XuqmSDK.shared.login(userId: "user_001", userSig: "your_user_sig_jwt")
|
||||
```
|
||||
|
||||
> `userSig` 由业务服务端用 `appSecret` 签发。若需更新登录态，直接重新登录即可。
|
||||
|
||||
---
|
||||
|
||||
@ -37,7 +35,7 @@ import XuqmSDK
|
||||
ImSDK.shared.setDelegate(self)
|
||||
|
||||
extension ViewController: ImEventDelegate {
|
||||
func imClientDidConnect() { print("WS connected") }
|
||||
func imClientDidConnect() { print("IM connected") }
|
||||
func imClientDidReceiveMessage(_ msg: ImMessage) { /* 处理单聊消息 */ }
|
||||
func imClientDidReceiveGroupMessage(_ msg: ImMessage) { /* 处理群消息 */ }
|
||||
func imClientDidReadMessage(_ msg: ImMessage) { /* 对方已读回执 */ }
|
||||
@ -250,5 +248,3 @@ ImSDK.shared.addConnectionStateListener { state in
|
||||
| `.quote` | 引用 | `{quotedMsgId, quotedContent, text}` |
|
||||
| `.merge` | 合并转发 | `{title, msgList}` |
|
||||
| `.revoked` | 撤回 | 系统内部填充 |
|
||||
|
||||
[→ 完整 API Reference](./api)
|
||||
|
||||
@ -52,7 +52,6 @@ dependencies: [
|
||||
```swift
|
||||
import XuqmCore
|
||||
|
||||
let config = SDKConfig(appId: "your_app_id", appSecret: "your_app_secret")
|
||||
XuqmSDK.shared.initialize(config: config)
|
||||
```
|
||||
|
||||
@ -69,7 +68,7 @@ try await XuqmSDK.shared.login(userId: "user_001", userSig: "your_user_sig_jwt")
|
||||
ImSDK.shared.setDelegate(self)
|
||||
|
||||
extension ViewController: ImEventDelegate {
|
||||
func imClientDidConnect() { print("WS connected") }
|
||||
func imClientDidConnect() { print("IM connected") }
|
||||
func imClientDidReceiveMessage(_ msg: ImMessage) { /* 处理单聊消息 */ }
|
||||
func imClientDidReceiveGroupMessage(_ msg: ImMessage) { /* 处理群消息 */ }
|
||||
func imClientDidReadMessage(_ msg: ImMessage) { /* 对方已读回执 */ }
|
||||
@ -81,7 +80,7 @@ extension ViewController: ImEventDelegate {
|
||||
|
||||
### 3. 连接状态监听
|
||||
|
||||
SDK 暴露 `connectionState` 属性与 `addConnectionStateListener`，方便业务层实时感知 WebSocket 连接状态：
|
||||
SDK 暴露 `connectionState` 属性与 `addConnectionStateListener`，方便业务层实时感知 IM 连接状态：
|
||||
|
||||
```swift
|
||||
// 查询当前状态
|
||||
@ -196,7 +195,7 @@ XuqmSDK.shared.initialize(config: config)
|
||||
// 登录（业务登录成功后调用一次）
|
||||
try await XuqmSDK.shared.login(userId: "user_001", userSig: userSig)
|
||||
// ↓ 自动触发
|
||||
// · ImSDK 连接 WebSocket
|
||||
// · ImSDK 连接 IM
|
||||
// · PushSDK 注册 APNs Token 并上报
|
||||
|
||||
// 登出（业务退出时调用一次）
|
||||
|
||||
@ -6,10 +6,10 @@
|
||||
|
||||
## Swift Package Manager（推荐）
|
||||
|
||||
在 Xcode → File → Add Package Dependencies 中输入：
|
||||
SDK 已发布到 Gitea，在 Xcode → File → Add Package Dependencies 中输入：
|
||||
|
||||
```
|
||||
https://github.com/xuqm/XuqmGroup-iOSSDK
|
||||
https://xuqinmin.com/xuqinmin12/XuqmGroup-iOSSDK
|
||||
```
|
||||
|
||||
或在 `Package.swift` 中添加：
|
||||
@ -22,7 +22,7 @@ let package = Package(
|
||||
name: "MyApp",
|
||||
platforms: [.iOS(.v16)],
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/xuqm/XuqmGroup-iOSSDK", from: "0.1.0")
|
||||
.package(url: "https://xuqinmin.com/xuqinmin12/XuqmGroup-iOSSDK", from: "0.1.0")
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
@ -81,7 +81,6 @@ let package = Package(
|
||||
```swift
|
||||
import XuqmSDK
|
||||
|
||||
let config = SDKConfig(appKey: "your_app_key", appSecret: "your_app_secret")
|
||||
XuqmSDK.shared.initialize(config: config)
|
||||
```
|
||||
|
||||
|
||||
@ -89,5 +89,39 @@ XuqmSDK.shared.initialize(config: config)
|
||||
|
||||
// 登录（业务登录成功后调用一次）
|
||||
try await XuqmSDK.shared.login(userId: "user_001", userSig: userSig)
|
||||
// UpdateSDK 在 checkAppUpdate 时自动携带 appId，无需额外登录操作
|
||||
// UpdateSDK 在 checkAppUpdate 时自动携带 appKey，无需额外登录操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 一键打包上传
|
||||
|
||||
SDK 提供 Fastlane `xuqm_release` lane，可一键完成 Archive、导出并上传至 XuqmGroup 版本管理服务：
|
||||
|
||||
```bash
|
||||
fastlane xuqm_release
|
||||
```
|
||||
|
||||
`Fastfile` 示例配置：
|
||||
|
||||
```ruby
|
||||
lane :xuqm_release do
|
||||
gym(
|
||||
scheme: "MyApp",
|
||||
export_method: "app-store",
|
||||
output_directory: "build"
|
||||
)
|
||||
|
||||
xuqm_upload(
|
||||
ipa_path: "build/MyApp.ipa",
|
||||
release_notes: File.read("CHANGELOG.md"),
|
||||
force_update: false
|
||||
)
|
||||
end
|
||||
```
|
||||
|
||||
任务执行流程：
|
||||
1. 执行 `gym` 构建 Release IPA
|
||||
2. 自动提取版本号、build 号、更新日志
|
||||
3. 上传 IPA 到 XuqmGroup 后台
|
||||
4. 返回发布结果
|
||||
|
||||
@ -1,13 +1,21 @@
|
||||
# 微信小程序 SDK 概览
|
||||
|
||||
**包名**：`@xuqm/miniprogram-sdk` · **版本**：0.1.0
|
||||
**包名**：`xuqm-group-wechat-mini-program-sdk` · **版本**：0.1.0
|
||||
|
||||
---
|
||||
|
||||
## npm 安装
|
||||
|
||||
在项目根目录创建 `.npmrc`：
|
||||
|
||||
```
|
||||
registry=https://nexus.xuqinmin.com/repository/npm/
|
||||
```
|
||||
|
||||
然后安装：
|
||||
|
||||
```bash
|
||||
npm install @xuqm/miniprogram-sdk
|
||||
npm install xuqm-group-wechat-mini-program-sdk
|
||||
```
|
||||
|
||||
或在微信开发者工具中：
|
||||
@ -20,13 +28,12 @@ npm install @xuqm/miniprogram-sdk
|
||||
## 初始化
|
||||
|
||||
```ts
|
||||
import { XuqmMiniProgramSDK } from '@xuqm/miniprogram-sdk'
|
||||
import { XuqmMiniProgramSDK } from 'xuqm-group-wechat-mini-program-sdk'
|
||||
|
||||
const sdk = new XuqmMiniProgramSDK()
|
||||
|
||||
sdk.init({
|
||||
appKey: 'your_app_key',
|
||||
appSecret: 'your_app_secret',
|
||||
debug: true, // 可选
|
||||
})
|
||||
```
|
||||
@ -40,9 +47,6 @@ sdk.init({
|
||||
```ts
|
||||
// 使用 UserSig 登录
|
||||
await sdk.login('user_001', 'your_user_sig_jwt')
|
||||
|
||||
// 或使用演示账号快速登录（仅测试）
|
||||
const token = await sdk.loginWithDemo('user_001', '123456')
|
||||
```
|
||||
|
||||
### 监听消息
|
||||
@ -131,30 +135,6 @@ const messages = await sdk.syncOfflineMessages()
|
||||
|
||||
---
|
||||
|
||||
## Push 接入（小程序通知）
|
||||
|
||||
微信小程序使用**订阅消息**和**服务通知**实现 Push，由服务端调用微信 API 下发。
|
||||
|
||||
XuqmGroup 小程序 SDK 本身不直接处理 Push Token（小程序无设备 Token 概念），业务方需要：
|
||||
|
||||
1. 用户订阅消息模板
|
||||
2. 业务服务端调用 XuqmGroup Server SDK 的 `send_push` 接口
|
||||
3. 或业务服务端直接调用微信服务端 API 下发订阅消息
|
||||
|
||||
```python
|
||||
# Python Server SDK 示例
|
||||
from xuqm_im_server_sdk import XuqmImServerSdk
|
||||
|
||||
sdk = XuqmImServerSdk(config)
|
||||
sdk.send_push(
|
||||
user_id="user_001",
|
||||
title="新消息",
|
||||
body="你有一条未读消息",
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Update 接入（小程序自带更新机制）
|
||||
|
||||
微信小程序的更新由微信客户端自动管理，开发者可通过微信 API 检查更新：
|
||||
|
||||
@ -28,7 +28,7 @@ await XuqmSDK.login({
|
||||
})
|
||||
```
|
||||
|
||||
> 如果集成了 `rn-im`，`XuqmSDK.login` 会自动触发 `ImSDK` 连接 WebSocket，业务侧无需单独调用 `ImSDK.login`。
|
||||
> 如果集成了 `rn-im`，`XuqmSDK.login` 会自动触发 `ImSDK` 连接，业务侧无需单独调用 `ImSDK.login`。
|
||||
|
||||
---
|
||||
|
||||
@ -197,5 +197,3 @@ interface ConversationData {
|
||||
isPinned: boolean
|
||||
}
|
||||
```
|
||||
|
||||
[→ 完整 API Reference](./api)
|
||||
|
||||
@ -53,12 +53,12 @@ import { XuqmSDK } from '@xuqm/rn-common'
|
||||
|
||||
// App 入口（如 App.tsx 的顶层）
|
||||
await XuqmSDK.initialize({
|
||||
appKey: 'your_app_key', // 在租户平台创建应用后获得
|
||||
logLevel: __DEV__ ? 'debug' : 'warn', // 可选
|
||||
appKey: 'your_app_key',
|
||||
logLevel: __DEV__ ? 'debug' : 'warn',
|
||||
})
|
||||
```
|
||||
|
||||
> SDK 内部自动处理服务器地址、WebSocket 连接、文件服务等配置，开发者无需关心。
|
||||
> SDK 内部自动处理服务器地址、IM 实时连接、文件服务等配置，开发者无需关心。
|
||||
|
||||
### 2. 统一登录
|
||||
|
||||
@ -176,11 +176,15 @@ const results = await ImSDK.searchMessages(params)
|
||||
|
||||
### 8. 推送 SDK
|
||||
|
||||
登录成功后 SDK **自动**注册设备 Token，业务侧无需手动调用。
|
||||
|
||||
如需自定义 Push 行为，可引入 `@xuqm/rn-push`：
|
||||
|
||||
```ts
|
||||
import { PushSDK } from '@xuqm/rn-push'
|
||||
|
||||
// 初始化并注册设备（登录后调用）
|
||||
await PushSDK.initialize({ userId: 'user_001' })
|
||||
// 手动设置接收推送开关
|
||||
await PushSDK.setReceivePush(false)
|
||||
```
|
||||
|
||||
### 9. 版本更新 SDK
|
||||
@ -274,7 +278,7 @@ UserSig 生成方式见 [安全设计文档](../../design/02-security-design.md)
|
||||
## 常见问题
|
||||
|
||||
**Q: 如何获取 appKey？**
|
||||
在 [租户平台](https://dev.xuqinmin.com) 注册账号后，创建应用即可获得 AppKey。
|
||||
在 [平台控制台](https://dev.xuqinmin.com) 注册账号后，创建应用即可获得 AppKey。
|
||||
|
||||
**Q: 为什么不需要传平台地址参数？**
|
||||
XuqmGroup 是托管平台，服务地址统一管理，与腾讯云 IM 等平台的设计一致，开发者只需关心业务逻辑。
|
||||
|
||||
@ -150,5 +150,40 @@ Update 模块与 IM、Push 模块共享同一套登录态：
|
||||
```ts
|
||||
await XuqmSDK.initialize({ appKey: 'your_app_key' })
|
||||
await XuqmSDK.login({ userId: 'user_001', userSig: 'your_user_sig_jwt' })
|
||||
// UpdateSDK 在 checkAppUpdate 时自动携带 appId，无需额外登录操作
|
||||
// UpdateSDK 在 checkAppUpdate 时自动携带 appKey，无需额外登录操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 一键打包上传
|
||||
|
||||
SDK 提供 `xuqm_release.mjs` 脚本，可一键完成 RN Bundle 构建并上传至 XuqmGroup 版本管理服务：
|
||||
|
||||
```bash
|
||||
node scripts/xuqm_release.mjs --platform android --env production
|
||||
```
|
||||
|
||||
脚本执行流程：
|
||||
1. 执行 `react-native bundle` 构建 JS Bundle
|
||||
2. 自动提取模块 ID、版本号、更新日志
|
||||
3. 上传 Bundle 到 XuqmGroup 后台
|
||||
4. 返回发布结果
|
||||
|
||||
常用参数：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--platform` | 平台：`android` / `ios` |
|
||||
| `--env` | 环境：`production` / `staging` |
|
||||
| `--moduleId` | 模块 ID（如 `home`）|
|
||||
| `--forceUpdate` | 是否强制更新 |
|
||||
|
||||
在 `package.json` 中添加快捷命令：
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"xuqm:release": "node scripts/xuqm_release.mjs --platform android --env production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@ -54,18 +54,6 @@ POST /api/im/auth/login
|
||||
|
||||
---
|
||||
|
||||
### WebSocket 连接
|
||||
|
||||
```
|
||||
WSS /ws/im?token=<token>&appId=<appId>
|
||||
```
|
||||
|
||||
- 协议：STOMP over WebSocket
|
||||
- 单聊订阅：`/user/{userId}/queue/messages`
|
||||
- 群聊订阅：`/topic/group/{groupId}`
|
||||
|
||||
---
|
||||
|
||||
### 发送消息
|
||||
|
||||
```
|
||||
@ -208,70 +196,6 @@ POST /api/im/admin/groups/{groupId}/read-receipts?appId=
|
||||
|
||||
---
|
||||
|
||||
## 版本管理服务（/api/v1/updates/ 和 /api/v1/rn/）
|
||||
|
||||
### 检查 App 更新
|
||||
|
||||
```
|
||||
GET /api/v1/updates/check?appId=&platform=ANDROID&versionCode=1
|
||||
```
|
||||
|
||||
**响应**
|
||||
|
||||
```json
|
||||
{
|
||||
"hasUpdate": true,
|
||||
"versionCode": 2,
|
||||
"versionName": "1.0.1",
|
||||
"forceUpdate": false,
|
||||
"downloadUrl": "https://cdn.example.com/app.apk",
|
||||
"appStoreUrl": null,
|
||||
"releaseNotes": "修复若干问题"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 检查 RN Bundle 热更新
|
||||
|
||||
```
|
||||
GET /api/v1/rn/check?appId=&moduleId=home&version=1.0.0&platform=ANDROID
|
||||
```
|
||||
|
||||
**响应**
|
||||
|
||||
```json
|
||||
{
|
||||
"hasUpdate": true,
|
||||
"version": "1.0.1",
|
||||
"downloadUrl": "https://cdn.example.com/bundles/home_1.0.1.bundle",
|
||||
"md5": "a1b2c3d4...",
|
||||
"size": 204800
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 下载 Bundle
|
||||
|
||||
`downloadUrl` 返回的 URL 可直接 `GET` 下载，响应体为 bundle 二进制内容。
|
||||
|
||||
---
|
||||
|
||||
## 租户服务（/api/）
|
||||
|
||||
### 创建应用（租户管理后台调用）
|
||||
|
||||
```
|
||||
POST /api/apps
|
||||
Authorization: Bearer <tenant_token>
|
||||
Content-Type: application/json
|
||||
|
||||
{ "name": "我的 App", "platform": "ANDROID" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### ImMessage
|
||||
|
||||
@ -37,7 +37,7 @@
|
||||
|
||||
---
|
||||
|
||||
## WebSocket 错误码
|
||||
## IM 连接错误码
|
||||
|
||||
| 关闭码 | 说明 | 处理建议 |
|
||||
|--------|------|----------|
|
||||
@ -56,7 +56,7 @@
|
||||
| 错误 | 说明 |
|
||||
|------|------|
|
||||
| `XuqmSDK not initialized. Call XuqmSDK.initialize() first.` | 未调用初始化 |
|
||||
| `WebSocket not connected` | 发送消息时未连接 |
|
||||
| `IM not connected` | 发送消息时未连接 |
|
||||
| `edit message failed` | 编辑消息接口返回空 |
|
||||
| `revoke message failed` | 撤回消息接口返回空 |
|
||||
|
||||
@ -71,22 +71,22 @@
|
||||
| 错误 | 说明 |
|
||||
|------|------|
|
||||
| `XuqmSDK not initialized. Call init() first.` | 未调用初始化 |
|
||||
| `WebSocket not connected` | WebSocket 未连接时发送消息 |
|
||||
| `IM not connected` | IM 未连接时发送消息 |
|
||||
| `IM token is empty` | 未登录或 Token 已清空 |
|
||||
|
||||
---
|
||||
|
||||
## 常见错误排查
|
||||
|
||||
### Q: 登录后 WebSocket 无法连接
|
||||
### Q: 登录后 IM 无法连接
|
||||
|
||||
- 检查 `userSig` 是否有效（未过期、签名正确）
|
||||
- 检查网络是否允许 WebSocket（防火墙、代理）
|
||||
- 检查 WebSocket 地址是否正确
|
||||
- 检查网络是否允许长连接（防火墙、代理）
|
||||
- 检查 IM 连接地址是否正确
|
||||
|
||||
### Q: 发送消息返回 FAILED
|
||||
|
||||
- 检查 WebSocket 连接状态
|
||||
- 检查 IM 连接状态
|
||||
- 检查 `toId` 是否有效
|
||||
- 检查 `appKey` 是否正确配置
|
||||
|
||||
@ -102,4 +102,4 @@
|
||||
- 检查 Token 是否在有效期内
|
||||
- 检查 HTTP Header 中 `Authorization: Bearer {token}` 格式
|
||||
|
||||
[→ Server API 文档 →](./api)
|
||||
[→ Server API 文档 →](/server/api)
|
||||
|
||||
116
docs-site/docs/server/go-sdk.md
普通文件
116
docs-site/docs/server/go-sdk.md
普通文件
@ -0,0 +1,116 @@
|
||||
# Go Server SDK
|
||||
|
||||
XuqmGroup 服务端 Go SDK，提供 IM 消息发送、群管理、Push 推送等能力。
|
||||
|
||||
---
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
go get xuqinmin.com/xuqinmin12/XuqmGroup-ServerSDK-Go
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 初始化
|
||||
|
||||
```go
|
||||
import xuqmsdk "xuqinmin.com/xuqinmin12/XuqmGroup-ServerSDK-Go"
|
||||
|
||||
client := xuqmsdk.NewClient(xuqmsdk.Config{
|
||||
BaseURL: "https://dev.xuqinmin.com",
|
||||
AppID: "your_app_id",
|
||||
AppSecret: "your_app_secret",
|
||||
})
|
||||
```
|
||||
|
||||
> 服务端 SDK 需要 `appSecret` 用于 HMAC 签名，`appSecret` 绝不下发到客户端。
|
||||
|
||||
---
|
||||
|
||||
## 发送消息
|
||||
|
||||
```go
|
||||
msg, err := client.SendMessage(xuqmsdk.SendMessageRequest{
|
||||
ToID: "user_002",
|
||||
ChatType: "SINGLE",
|
||||
MsgType: "TEXT",
|
||||
Content: "Hello from Go SDK!",
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
log.Printf("消息已发送: %s", msg.ID)
|
||||
```
|
||||
|
||||
### 发送群消息
|
||||
|
||||
```go
|
||||
msg, err := client.SendMessage(xuqmsdk.SendMessageRequest{
|
||||
ToID: "group_xxx",
|
||||
ChatType: "GROUP",
|
||||
MsgType: "TEXT",
|
||||
Content: "大家好",
|
||||
})
|
||||
```
|
||||
|
||||
### 撤回消息
|
||||
|
||||
```go
|
||||
err := client.RevokeMessage("message_id")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 群管理
|
||||
|
||||
```go
|
||||
// 创建群组
|
||||
group, err := client.CreateGroup(xuqmsdk.CreateGroupRequest{
|
||||
Name: "项目讨论",
|
||||
MemberIDs: []string{"user_001", "user_002"},
|
||||
})
|
||||
|
||||
// 添加群成员
|
||||
err = client.AddGroupMember("group_xxx", "user_003")
|
||||
|
||||
// 移除群成员
|
||||
err = client.RemoveGroupMember("group_xxx", "user_003")
|
||||
|
||||
// 获取群列表
|
||||
groups, err := client.ListGroups()
|
||||
|
||||
// 获取群成员
|
||||
members, err := client.ListGroupMembers("group_xxx")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Push 推送
|
||||
|
||||
```go
|
||||
err := client.SendPush(xuqmsdk.SendPushRequest{
|
||||
UserID: "user_001",
|
||||
Title: "新消息",
|
||||
Body: "你有一条未读消息",
|
||||
Payload: map[string]string{"chatId": "user_002"},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误处理
|
||||
|
||||
SDK 返回的错误实现了标准 `error` 接口。业务方可根据错误类型做不同处理：
|
||||
|
||||
```go
|
||||
msg, err := client.SendMessage(req)
|
||||
if err != nil {
|
||||
// 可断言为 *xuqmsdk.APIError 获取 HTTP 状态码和详细错误信息
|
||||
if apiErr, ok := err.(*xuqmsdk.APIError); ok {
|
||||
log.Printf("API 错误: status=%d, code=%d, message=%s", apiErr.Status, apiErr.Code, apiErr.Message)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[→ Server API 文档 →](/server/api)
|
||||
112
docs-site/docs/server/python-sdk.md
普通文件
112
docs-site/docs/server/python-sdk.md
普通文件
@ -0,0 +1,112 @@
|
||||
# Python Server SDK
|
||||
|
||||
XuqmGroup 服务端 Python SDK，提供 IM 消息发送、群管理、Push 推送等能力。
|
||||
|
||||
---
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
pip install xuqm-im-server-sdk
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 初始化
|
||||
|
||||
```python
|
||||
from xuqm_im_server_sdk import XuqmImServerSdk
|
||||
|
||||
sdk = XuqmImServerSdk(
|
||||
base_url="https://dev.xuqinmin.com",
|
||||
app_id="your_app_id",
|
||||
app_secret="your_app_secret",
|
||||
)
|
||||
```
|
||||
|
||||
> 服务端 SDK 需要 `app_secret` 用于 HMAC 签名，`app_secret` 绝不下发到客户端。
|
||||
|
||||
---
|
||||
|
||||
## 发送消息
|
||||
|
||||
```python
|
||||
msg = sdk.send_message(
|
||||
to_id="user_002",
|
||||
chat_type="SINGLE",
|
||||
msg_type="TEXT",
|
||||
content="Hello from Python SDK!",
|
||||
)
|
||||
print(f"消息已发送: {msg['id']}")
|
||||
```
|
||||
|
||||
### 发送群消息
|
||||
|
||||
```python
|
||||
msg = sdk.send_message(
|
||||
to_id="group_xxx",
|
||||
chat_type="GROUP",
|
||||
msg_type="TEXT",
|
||||
content="大家好",
|
||||
)
|
||||
```
|
||||
|
||||
### 撤回消息
|
||||
|
||||
```python
|
||||
sdk.revoke_message("message_id")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 群管理
|
||||
|
||||
```python
|
||||
# 创建群组
|
||||
group = sdk.create_group(
|
||||
name="项目讨论",
|
||||
member_ids=["user_001", "user_002"],
|
||||
)
|
||||
|
||||
# 添加群成员
|
||||
sdk.add_group_member("group_xxx", "user_003")
|
||||
|
||||
# 移除群成员
|
||||
sdk.remove_group_member("group_xxx", "user_003")
|
||||
|
||||
# 获取群列表
|
||||
groups = sdk.list_groups()
|
||||
|
||||
# 获取群成员
|
||||
members = sdk.list_group_members("group_xxx")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Push 推送
|
||||
|
||||
```python
|
||||
sdk.send_push(
|
||||
user_id="user_001",
|
||||
title="新消息",
|
||||
body="你有一条未读消息",
|
||||
payload={"chatId": "user_002"},
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误处理
|
||||
|
||||
SDK 在请求失败时会抛出 `XuqmAPIError` 异常：
|
||||
|
||||
```python
|
||||
from xuqm_im_server_sdk import XuqmAPIError
|
||||
|
||||
try:
|
||||
msg = sdk.send_message(to_id="user_002", chat_type="SINGLE", msg_type="TEXT", content="Hello")
|
||||
except XuqmAPIError as e:
|
||||
print(f"API 错误: status={e.status}, code={e.code}, message={e.message}")
|
||||
```
|
||||
|
||||
[→ Server API 文档 →](/server/api)
|
||||
@ -1,6 +1,6 @@
|
||||
# Vue3 IM 接入
|
||||
|
||||
基于 `@xuqm/vue3-sdk` 实现即时通讯功能，支持原生 WebSocket + STOMP 协议。
|
||||
基于 `@xuqm/vue3-sdk` 实现即时通讯功能。
|
||||
|
||||
---
|
||||
|
||||
@ -13,7 +13,6 @@ import { init } from '@xuqm/vue3-sdk'
|
||||
|
||||
init({
|
||||
appKey: 'your_app_key',
|
||||
appSecret: 'your_app_secret',
|
||||
})
|
||||
```
|
||||
|
||||
@ -222,5 +221,3 @@ await removeFriend('user_002')
|
||||
| `MERGE` | 合并转发 |
|
||||
| `FORWARD` | 转发 |
|
||||
| `REVOKED` | 撤回 |
|
||||
|
||||
[→ 完整 API Reference](./api)
|
||||
|
||||
@ -8,7 +8,6 @@
|
||||
|------|------|
|
||||
| `useXuqm()` | 全局初始化 Composable |
|
||||
| `useIm()` | IM 单聊/群聊响应式状态 |
|
||||
| `useUpdate()` | 版本检查与热更新 |
|
||||
| `XuqmProvider` | 可选根组件（自动初始化）|
|
||||
|
||||
## 安装
|
||||
@ -100,17 +99,6 @@ subscribeGroup(group.id)
|
||||
await sendMessage(group.id, 'GROUP', 'TEXT', '大家好')
|
||||
```
|
||||
|
||||
### 6. 检查 App/RN 更新
|
||||
|
||||
```ts
|
||||
import { useUpdate } from '@xuqm/vue3-sdk'
|
||||
|
||||
const { checkAppUpdate, checkRNUpdate } = useUpdate()
|
||||
|
||||
const appInfo = await checkAppUpdate(1) // 当前 versionCode
|
||||
const rnBundle = await checkRNUpdate('home', '1.0.0')
|
||||
```
|
||||
|
||||
## 响应式状态
|
||||
|
||||
`useIm()` 返回的响应式 ref：
|
||||
@ -119,7 +107,7 @@ const rnBundle = await checkRNUpdate('home', '1.0.0')
|
||||
const {
|
||||
messages, // Ref<ImMessage[]> 单聊消息列表
|
||||
groupMessages, // Ref<ImMessage[]> 当前群消息列表
|
||||
connected, // Ref<boolean> WS 连接状态
|
||||
connected, // Ref<boolean> IM 连接状态
|
||||
currentUser, // Ref<string | null> 当前登录用户
|
||||
} = useIm()
|
||||
```
|
||||
|
||||
@ -64,10 +64,8 @@ import { init } from '@xuqm/vue3-sdk'
|
||||
|
||||
init({
|
||||
appKey: 'your_app_key',
|
||||
appSecret: 'your_app_secret',
|
||||
debug: true, // 可选
|
||||
baseUrl: 'https://...', // 可选，默认 https://dev.xuqinmin.com
|
||||
wsUrl: 'wss://.../ws/im', // 可选，默认 wss://dev.xuqinmin.com/ws/im
|
||||
})
|
||||
```
|
||||
|
||||
|
||||
正在加载...
在新工单中引用
屏蔽一个用户
