XuqmGroup-Web/docs-site/docs/rn/index.md

React Native SDK 接入指南

包名：@xuqm/rn-sdk · 版本：0.3.x（v0.4.0 规划中，将引入 UserSig 鉴权）

注意：v0.4.0 将是 Breaking 版本。initialize() 将移除 serverUrl 参数，login() 将改为 UserSig 鉴权模式，详见迁移指南。

---

功能模块

包	功能
@xuqm/rn-common	初始化、网络、设备信息（必须）
@xuqm/rn-im	单聊、群聊、消息收发、本地 DB（WatermelonDB）
@xuqm/rn-push	推送设备 Token 上报
@xuqm/rn-update	App 版本检查、RN Bundle 热更新
@xuqm/rn-sdk	以上所有模块的 meta 包（推荐直接使用）

---

安装

在项目根目录创建 .npmrc：

@xuqm:registry=https://nexus.xuqinmin.com/repository/npm/

安装 meta 包（包含全部功能）：

yarn add @xuqm/rn-sdk

---

快速接入（当前 v0.3.x）

1. 初始化

初始化只需传入 appId，服务器地址由 SDK 内置，不需要传 serverUrl。

import { XuqmSDK } from '@xuqm/rn-sdk'

// App 入口（如 App.tsx 的顶层）
await XuqmSDK.initialize({
  appId:    'your_app_id',   // 在租户平台创建应用后获得
  logLevel: __DEV__ ? 'debug' : 'warn',  // 可选
})

SDK 内部自动处理服务器地址、WebSocket 连接、文件服务等配置，开发者无需关心。

2. IM 登录

import { ImSDK } from '@xuqm/rn-sdk'

// 登录（userId + 用户信息）
// v0.3.x：传入用户信息，本地 DB 按 userId 自动隔离
await ImSDK.login('user_001', 'nickname', 'https://avatar.url')

// 推荐提前在您的服务端生成 UserSig（v0.4.0 正式采用）
// const userSig = await yourApi.getUserSig(userId)
// await ImSDK.login('user_001', userSig)

3. 消息收发

// 监听实时消息
ImSDK.addEventListener('message', (msg) => {
  console.log('收到消息:', msg.msgType, msg.content)
})

// 发送文本消息
const msg = await ImSDK.sendMessage(
  'user_002',   // toId
  'SINGLE',     // chatType: 'SINGLE' | 'GROUP'
  'TEXT',       // msgType
  'Hello!'      // content
)

// 发送图片（自动上传到 file-service）
const msg = await ImSDK.sendImageMessage(
  'user_002', 'SINGLE',
  '/path/to/image.jpg',  // 本地 URI
  800, 600               // 宽高（可选）
)

// 获取历史消息（单聊）
const history = await ImSDK.fetchHistory('user_002', page, size)

// 获取群历史消息
const groupHistory = await ImSDK.fetchGroupHistory('group_xxx', page, size)

4. 会话列表

// 订阅会话变化
const unsub = ImSDK.subscribeConversations((conversations) => {
  // conversations: ConversationData[]
  console.log(conversations)
})

// 置顶会话
await ImSDK.setConversationPinned('user_002', 'SINGLE', true)

// 免打扰
await ImSDK.setConversationMuted('group_xxx', 'GROUP', true)

// 标记已读
await ImSDK.markRead('user_002')

5. 群组管理

// 创建群组
const group = await ImSDK.createGroup('项目讨论', ['user_002', 'user_003'])

// 群组列表（仅返回当前用户所在的群）
const groups = await ImSDK.listGroups()

// 添加成员
await ImSDK.addGroupMember('group_xxx', 'user_004')

// 移除成员（需要管理员权限）
await ImSDK.removeGroupMember('group_xxx', 'user_004')

// 退出群聊
await ImSDK.leaveGroup('group_xxx')

6. 好友关系

// 好友列表
const friends = await ImSDK.listFriends()

// 添加好友（双向）
await ImSDK.addFriend('user_002')

// 删除好友（双向）
await ImSDK.removeFriend('user_002')

7. 消息搜索（本地）

import { ImSDK } from '@xuqm/rn-sdk'
import type { MessageSearchParams } from '@xuqm/rn-sdk'

const params: MessageSearchParams = {
  keyword: '会议',        // 关键词搜索
  toId: 'user_002',      // 限定会话（可选）
  chatType: 'SINGLE',    // 限定类型（可选）
  msgTypes: ['TEXT'],    // 限定消息类型（可选）
  limit: 20,
}
const results = await ImSDK.searchMessages(params)

8. 推送 SDK

import { PushSDK } from '@xuqm/rn-sdk'

// 初始化并注册设备（登录后调用）
await PushSDK.initialize({ userId: 'user_001' })

9. 版本更新 SDK

import { UpdateSDK } from '@xuqm/rn-sdk'

// 检查 App 原生更新
const appUpdate = await UpdateSDK.checkAppUpdate()
if (appUpdate?.needsUpdate) {
  console.log('新版本:', appUpdate.versionName)
  // Linking.openURL(appUpdate.downloadUrl)
}

// 检查 RN Bundle 热更新
const rnUpdate = await UpdateSDK.checkRnUpdate('your_module_id')
if (rnUpdate?.needsUpdate) {
  await UpdateSDK.downloadAndApplyBundle(rnUpdate)
}

10. 断开连接

ImSDK.disconnect()

---

TypeScript 类型参考

// 消息
interface ImMessage {
  id:         string
  fromId:     string
  toId:       string
  chatType:   'SINGLE' | 'GROUP'
  msgType:    'TEXT' | 'IMAGE' | 'AUDIO' | 'VIDEO' | 'FILE' |
              'LOCATION' | 'NOTIFY' | 'CUSTOM' | 'RICH_TEXT' |
              'CALL_AUDIO' | 'CALL_VIDEO' | 'FORWARD' | 'REVOKED'
  content:    string    // JSON 字符串，结构按 msgType 不同
  status:     'SENDING' | 'SENT' | 'DELIVERED' | 'READ' | 'FAILED' | 'REVOKED'
  createdAt:  number    // Unix 毫秒
}

// 会话
interface ConversationData {
  targetId:       string
  chatType:       'SINGLE' | 'GROUP'
  lastMsgContent: string
  lastMsgType:    string
  lastMsgTime:    number
  unreadCount:    number
  isMuted:        boolean
  isPinned:       boolean
}

// 群组
interface ImGroup {
  id:         string
  name:       string
  creatorId:  string
  memberIds:  string    // JSON 数组字符串
  adminIds:   string
  createdAt:  number
}

---

迁移指南（v0.3.x → v0.4.0）

v0.4.0 预计改动（Breaking Changes）：

// 初始化
- await XuqmSDK.initialize({ appId: 'xxx', serverUrl: 'https://...' })
+ await XuqmSDK.initialize({ appId: 'xxx' })   // serverUrl 内置，无需传入

// IM 登录（改为 UserSig 鉴权，密码不再传入 SDK）
- await ImSDK.login(userId, nickname, avatar, dbName)
+ const userSig = await yourServer.getUserSig(userId)  // 您的服务端签发
+ await ImSDK.login(userId, userSig, { nickname, avatar })
// dbName 自动由 appId + userId 派生，无需传入

// loginWithToken 废弃
- await ImSDK.loginWithToken(userId, token, dbName)
+ // 统一使用 login(userId, userSig)

UserSig 生成方式见安全设计文档。

---

常见问题

Q: 如何获取 appId？ 在 租户平台 注册账号后，创建应用即可获得 AppId。

Q: 为什么不需要传 serverUrl？ XuqmGroup 是托管平台，服务地址统一管理，与腾讯云 IM 等平台的设计一致，开发者只需关心业务逻辑。

Q: UserSig 是什么？（v0.4.0） UserSig 是您的业务服务端用 AppSecret 为用户签发的安全凭证，有效期可配置。AppSecret 绝不下发到客户端。

Q: 本地消息存储在哪里？ 使用 WatermelonDB（SQLite），按 appId + userId 自动隔离，多账号切换安全。