From 27d298a6222386abd14b701007010c722099388e Mon Sep 17 00:00:00 2001 From: XuqmGroup Date: Fri, 1 May 2026 22:18:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E5=90=84=E5=B9=B3=E5=8F=B0=20SDK=20=E9=9B=86=E6=88=90=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=88V2=20=E7=AE=80=E5=8C=96=E7=99=BB=E5=BD=95?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Android: 移除 UserSig 续签章节，更新登录示例 - iOS: 移除过期检测章节，更新登录示例 - RN: 更新登录示例 - Vue3: 更新登录示例 - HarmonyOS: 更新登录示例 - Server API: 更新 /api/im/auth/login 参数说明与签名规则 --- docs-site/docs/android/index.md | 52 +++++++++++++++------------------ docs-site/docs/harmony/index.md | 6 ++-- docs-site/docs/ios/index.md | 35 +++++++++++----------- docs-site/docs/rn/index.md | 17 ++++++----- docs-site/docs/server/api.md | 20 +++++++++++-- docs-site/docs/vue3/index.md | 2 +- 6 files changed, 72 insertions(+), 60 deletions(-) diff --git a/docs-site/docs/android/index.md b/docs-site/docs/android/index.md index 287b51b..c5436a8 100644 --- a/docs-site/docs/android/index.md +++ b/docs-site/docs/android/index.md @@ -1,12 +1,12 @@ # Android SDK 接入指南 -**版本**：0.4.x（UserSig 鉴权）· **最低 Android 版本**：API 24 (Android 7.0) · **语言**：Kotlin +**版本**：0.5.x（UserSig 鉴权 · 简化登录）· **最低 Android 版本**：API 24 (Android 7.0) · **语言**：Kotlin ## 功能模块 | 模块 | Artifact | 功能 | |------|----------|------| -| sdk-core | `com.xuqm:sdk-core` | 初始化、网络、鉴权、UserSig 续签 | +| sdk-core | `com.xuqm:sdk-core` | 初始化、网络、鉴权 | | sdk-im | `com.xuqm:sdk-im` | 单聊、群聊、消息收发、会话、好友、群组 | | sdk-push | `com.xuqm:sdk-push` | 自动检测厂商、设备 Token 注册（华为/小米/OPPO/vivo/荣耀/FCM） | | sdk-update | `com.xuqm:sdk-update` | App 更新检查、下载安装 | @@ -52,13 +52,11 @@ XuqmSDK.initialize( ```kotlin // 登录（协程 suspend 函数） +// 只需要 userId + userSig，不需要 nickname / avatar / expiresAt lifecycleScope.launch { XuqmSDK.login( userId = "user_001", userSig = "your_user_sig_jwt", // 由业务服务端签发 - nickname = "张三", - avatar = "https://...", - userSigExpiresAt = 1893456000000L, // UserSig 过期时间戳（毫秒），可选 ) } @@ -118,20 +116,15 @@ ImSDK.deleteConversation(targetId, "SINGLE") ### 6. Push 多厂商接入 -SDK 在登录后会自动检测手机厂商并初始化对应 Push 服务。业务层通常无需手动调用，但可根据需要主动控制： +SDK 在 `XuqmSDK.login()` 成功后会自动检测手机厂商、初始化对应 Push SDK、获取 Token 并上报到 Push 服务端。业务层**无需手动调用**任何 Push 注册 API。 + +如需主动控制，可调用： ```kotlin -// 手动检测当前设备厂商 +// 检测当前设备厂商 val vendor = PushSDK.detectVendor() // 返回：HUAWEI / XIAOMI / OPPO / VIVO / HONOR / FCM -// 手动初始化各厂商 Push SDK（通常由 onSdkLogin 自动调用） -PushSDK.initializeVendors(context) - -// 手动绑定/解绑 IM 用户与 Push Token -PushSDK.bindImUser(context, userId = "user_001") -PushSDK.unbindImUser(userId = "user_001") - // 开启或关闭推送接收 PushSDK.setReceivePush(context, enabled = false) ``` @@ -147,26 +140,27 @@ PushSDK.setReceivePush(context, enabled = false) | 荣耀 | `com.hihonor.mcs:mcs-push` | 需在荣耀开发者服务平台配置 | | FCM | `com.google.firebase:firebase-messaging` | 模拟器无 Google Play 服务时会 fallback | -### 7. UserSig 续签 +### 7. 多模块统一登录 -在 `UserSig` 即将过期（默认提前 5 分钟）时，SDK 会触发续签回调。业务层应在回调中向自己的服务端申请新的 UserSig，然后重新调用 `XuqmSDK.login()` 刷新 Token 和定时器。 +无论集成了哪些模块（IM、Push、Update），**初始化和登录永远只做一次**： ```kotlin -// 设置续签监听器（建议在初始化后、登录前设置） -XuqmSDK.setUserSigRefreshListener { - // 异步获取新 UserSig - lifecycleScope.launch { - val newUserSig = yourBackend.refreshUserSig("user_001") - XuqmSDK.login( - userId = "user_001", - userSig = newUserSig, - userSigExpiresAt = newExpiryTimeMs, - ) - } -} +// 初始化（Application.onCreate） +XuqmSDK.initialize(context, appKey = "your_app_key") + +// 登录（业务登录成功后调用一次） +XuqmSDK.login(userId = "user_001", userSig = "jwt_token") +// ↓ 自动触发 +// · ImSDK.onSdkLogin → 连接 WebSocket +// · PushSDK.onSdkLogin → 注册厂商 Token 并上报 +// · UpdateSDK.onSdkLogin → 无需额外操作（检查时自动携带凭证） + +// 登出（业务退出时调用一次） +XuqmSDK.logout() +// ↓ 自动触发所有模块清理 ``` -> **注意**：`userSigExpiresAt` 为 Unix 时间戳（毫秒）。若登录时不传该值，则不会启动续签定时器。 +> **注意**：`userSig` 一旦获取即永久有效，SDK 侧不做过期检查与续签。如需撤销权限，业务侧可在租户平台重置 `appSecret` 或拉黑账号。 ### 8. 版本更新 diff --git a/docs-site/docs/harmony/index.md b/docs-site/docs/harmony/index.md index fc461ef..af564e5 100644 --- a/docs-site/docs/harmony/index.md +++ b/docs-site/docs/harmony/index.md @@ -54,9 +54,11 @@ export default class EntryAbility extends UIAbility { ### 2. IM 登录 ```typescript -import { ImSDK } from '@xuqm/harmony-sdk' +import { XuqmSDK, ImSDK } from '@xuqm/harmony-sdk' -await ImSDK.login('user_001', '张三') +// 只需要 userId + userSig +await XuqmSDK.login('user_001', 'your_user_sig_jwt') +// 如果集成了 ImSDK，XuqmSDK.login 会自动触发 WebSocket 连接 ``` ### 3. 监听消息 diff --git a/docs-site/docs/ios/index.md b/docs-site/docs/ios/index.md index 364e377..f52060f 100644 --- a/docs-site/docs/ios/index.md +++ b/docs-site/docs/ios/index.md @@ -6,7 +6,7 @@ | 模块 | 功能 | |------|------| -| XuqmCore | 初始化、网络、鉴权、UserSig 过期检测 | +| XuqmCore | 初始化、网络、鉴权 | | XuqmIM | 单聊、群聊、消息收发（15 种类型）、连接状态监听 | | XuqmPush | APNs 设备 Token 注册、FCM 备选、通知处理 | | XuqmUpdate | App 版本检查、App Store 跳转 | @@ -61,12 +61,10 @@ XuqmSDK.shared.initialize(config: config) ```swift import XuqmIM -// 方式一：使用 UserSig 登录（推荐生产环境） +// 使用 UserSig 登录（推荐生产环境） +// 只需要 userId + userSig，不需要 nickname / avatar / expiresAt try await XuqmSDK.shared.login(userId: "user_001", userSig: "your_user_sig_jwt") -// 方式二：Demo 环境快速登录 -try await ImSDK.shared.loginWithDemo(userId: "user_001", password: "123456") - // 设置事件代理 ImSDK.shared.setDelegate(self) @@ -187,24 +185,25 @@ func application(_ application: UIApplication, didRegisterForRemoteNotifications try await PushSDK.shared.registerFcmToken(fcmToken, userId: "user_001") ``` -### 9. UserSig 过期检测 +### 9. 多模块统一登录 -`XuqmSDK` 会在登录时解析 UserSig JWT 的 `exp` 字段，并在过期前 5 分钟触发 `onUserSigExpired` 回调。业务层应在此回调中重新获取 UserSig 并登录。 +无论集成了哪些模块（IM、Push、Update），**初始化和登录永远只做一次**： ```swift -// 设置过期回调（建议在初始化后设置） -XuqmSDK.shared.onUserSigExpired = { [weak self] in - Task { - let newUserSig = await self?.yourBackend.refreshUserSig() - try? await XuqmSDK.shared.login(userId: "user_001", userSig: newUserSig) - } -} +// 初始化 +XuqmSDK.shared.initialize(config: config) + +// 登录（业务登录成功后调用一次） +try await XuqmSDK.shared.login(userId: "user_001", userSig: userSig) +// ↓ 自动触发 +// · ImSDK 连接 WebSocket +// · PushSDK 注册 APNs Token 并上报 + +// 登出（业务退出时调用一次） +XuqmSDK.shared.logout() ``` -> **注意**： -> - 回调触发时机为 `exp - 300s`（提前 5 分钟）。 -> - 调用 `logout()` 后内部 Timer 会被自动 `invalidate`。 -> - 若 UserSig 已过期（`exp <= now`），回调会立即触发。 +> **注意**：`userSig` 一旦获取即永久有效，SDK 侧不做过期检测与续签。 ### 10. 检查更新 diff --git a/docs-site/docs/rn/index.md b/docs-site/docs/rn/index.md index 82619e4..354eb7d 100644 --- a/docs-site/docs/rn/index.md +++ b/docs-site/docs/rn/index.md @@ -60,18 +60,21 @@ await XuqmSDK.initialize({ > SDK 内部自动处理服务器地址、WebSocket 连接、文件服务等配置，开发者无需关心。 -### 2. IM 登录 +### 2. 统一登录 ```ts +import { XuqmSDK } from '@xuqm/rn-common' import { ImSDK } from '@xuqm/rn-im' -// 登录（userId + 用户信息） -// v0.3.x：传入用户信息，本地 DB 按 userId 自动隔离 -await ImSDK.login('user_001', 'nickname', 'https://avatar.url') +// 登录只需要 userId + userSig +// nickname / avatar 不再通过登录接口传入 +await XuqmSDK.login({ + userId: 'user_001', + userSig: 'your_user_sig_jwt', +}) -// 推荐提前在您的服务端生成 UserSig（v0.4.0 正式采用） -// const userSig = await yourApi.getUserSig(userId) -// await ImSDK.login('user_001', userSig) +// 如果集成了 rn-im，XuqmSDK.login 会自动触发 ImSDK 连接 +// 业务侧无需单独调用 ImSDK.login ``` ### 3. 消息收发 diff --git a/docs-site/docs/server/api.md b/docs-site/docs/server/api.md index 19644c0..82e191d 100644 --- a/docs-site/docs/server/api.md +++ b/docs-site/docs/server/api.md @@ -30,14 +30,28 @@ POST /api/im/auth/login |------|------|------| | `appId` | 是 | 应用 ID | | `userId` | 是 | 用户 ID | -| `nickname` | 是 | 昵称 | + +**请求头** + +| 头 | 必填 | 说明 | +|----|------|------| +| `X-App-Timestamp` | 是 | 当前时间戳（毫秒） | +| `X-App-Nonce` | 是 | 随机字符串 | +| `X-App-Signature` | 是 | HmacSHA256 签名 | + +**签名 Payload**（已简化，不再包含 nickname/avatar）： +``` +{appId}\n{userId}\n{timestamp}\n{nonce} +``` **响应** ```json -{ "token": "eyJ..." } +{ "token": "eyJ...", "expiresAt": 9223372036854775807 } ``` +> `expiresAt` 为极大值（约 100 年），表示 token 永久有效。SDK 侧不做过期检查。 + --- ### WebSocket 连接 @@ -255,7 +269,7 @@ Content-Type: application/json | HTTP 状态 | code | 说明 | |-----------|------|------| | 400 | 400 | 请求参数错误 | -| 401 | 401 | Token 无效或过期 | +| 401 | 401 | Token 无效或签名验证失败 | | 403 | 403 | 无权限操作（如撤回他人消息）| | 404 | 404 | 资源不存在 | | 500 | 500 | 服务器内部错误 | diff --git a/docs-site/docs/vue3/index.md b/docs-site/docs/vue3/index.md index 4a7e77f..afd83f0 100644 --- a/docs-site/docs/vue3/index.md +++ b/docs-site/docs/vue3/index.md @@ -51,7 +51,7 @@ import { useIm } from '@xuqm/vue3-sdk' const { messages, connected, login, sendMessage, revokeMessage } = useIm() -onMounted(() => login('user_001', '张三')) +onMounted(() => login('user_001', 'your_user_sig_jwt'))