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

React Native SDK 概览

包名：@xuqm/rn-sdk · 版本：0.1.0 · 支持：React Native 0.73+、Expo 50+

功能模块

导出	功能
XuqmSDK	全局初始化
ImSDK	单聊、群聊、消息收发、历史记录
UpdateSDK	App 版本检查、RN Bundle 热更新
PushSDK	设备 Token 上报

安装

从 Nexus 私有仓库安装

在项目根目录创建 .npmrc：

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

然后安装：

npm install @xuqm/rn-sdk
# 或
yarn add @xuqm/rn-sdk

快速接入

1. 初始化（一次即可，在 App 启动时调用）

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

XuqmSDK.init({
  appId:      'your_app_id',
  appKey:     'your_app_id',
  appSecret:  'your_app_secret',
  apiBaseUrl: 'https://sentry.xuqinmin.com',
  imWsUrl:    'wss://sentry.xuqinmin.com/ws/im',
  debug:      __DEV__,
})

2. IM 登录

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

await ImSDK.login('user_001', '张三')

3. 监听消息与连接事件

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

const listener: ImEventListener = {
  onConnected()           { console.log('WS connected') },
  onDisconnected(reason)  { console.log('WS disconnected:', reason) },
  onMessage(msg)          { /* 单聊/群聊消息 */ },
  onGroupMessage(msg)     { /* 群消息（独立回调） */ },
  onError(err)            { console.error(err) },
}

ImSDK.addListener(listener)

// 组件卸载时移除
return () => {
  ImSDK.removeListener(listener)
  ImSDK.disconnect()
}

4. 发送消息

// 文本
const sent = await ImSDK.sendMessage('user_002', 'SINGLE', 'TEXT', 'Hello!')

// 图片（content 为 JSON 字符串）
const sent = await ImSDK.sendMessage('user_002', 'SINGLE', 'IMAGE', JSON.stringify({
  url: 'https://cdn.example.com/img.jpg',
  width: 800, height: 600,
}))

5. 撤回消息

const revoked = await ImSDK.revokeMessage(msg.id)

6. 拉取历史

// 单聊历史（page=0, size=50）
const history = await ImSDK.fetchHistory('user_002', 0, 50)

// 群历史
const gHistory = await ImSDK.fetchGroupHistory(groupId, 0, 50)

7. 群聊

// 创建群（自动将自己加入成员列表）
const group = await ImSDK.createGroup('开发讨论组', ['user_001', 'user_002'])

// 订阅群 WebSocket topic
ImSDK.subscribeGroup(group.id)

// 列出所有群
const groups = await ImSDK.listGroups()

// 发群消息
const sent = await ImSDK.sendMessage(group.id, 'GROUP', 'TEXT', '大家好')

8. 检查 App 更新

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

const info = await UpdateSDK.checkAppUpdate(1 /* 当前 versionCode */)
if (info) {
  console.log(info.versionName, info.forceUpdate, info.downloadUrl)
}

9. RN Bundle 热更新（三步流程）

import AsyncStorage from '@react-native-async-storage/async-storage'

// Step 1: 检查是否有新版本
const bundle = await UpdateSDK.checkRNUpdate('home', '1.0.0')
if (!bundle) return // 已是最新

// Step 2: 下载 bundle
const content = await UpdateSDK.downloadBundle(bundle.downloadUrl)

// Step 3: 缓存，下次启动由 BundleRuntime 加载
await AsyncStorage.setItem('rn_bundle_home', JSON.stringify({
  version: bundle.version,
  md5:     bundle.md5,
  content,
  cachedAt: new Date().toISOString(),
}))

提示：运行时替换（热加载）需对接原生 BundleRuntime，参考 ProjectFrameReactNative 架构文档。

完整消息类型

type MsgType =
  | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'FILE'
  | 'CUSTOM' | 'LOCATION' | 'NOTIFY' | 'RICH_TEXT'
  | 'CALL_AUDIO' | 'CALL_VIDEO' | 'FORWARD' | 'REVOKED'

每种类型的 content 格式：

MsgType	content
TEXT	纯文本字符串
IMAGE	{"url":"...","width":800,"height":600,"thumbnailUrl":"..."}
VIDEO	{"url":"...","duration":30,"thumbnailUrl":"...","size":1048576}
AUDIO	{"url":"...","duration":12,"size":204800}
FILE	{"url":"...","name":"report.pdf","size":512000,"mimeType":"application/pdf"}
LOCATION	{"lat":39.9042,"lng":116.4074,"address":"北京市东城区","title":"天安门"}
CUSTOM	任意 JSON 字符串
NOTIFY	{"title":"系统通知","content":"服务器维护","level":"INFO"}
RICH_TEXT	{"html":"<b>加粗</b>内容"}
CALL_AUDIO	{"callId":"uuid","action":"INVITE","callerName":"张三"}
CALL_VIDEO	{"callId":"uuid","action":"INVITE","callerName":"张三"}
FORWARD	{"originalMsgId":"...","originalContent":"原始内容","originalSender":"张三"}
REVOKED	服务端下发，客户端只读

TypeScript 类型定义

interface ImMessage {
  id:         string
  appId:      string
  fromUserId: string
  toId:       string
  chatType:   'SINGLE' | 'GROUP'
  msgType:    MsgType
  content:    string
  status:     'SENT' | 'REVOKED'
  createdAt:  string   // ISO 8601
}

interface ImGroup {
  id:        string
  appId:     string
  name:      string
  creatorId: string
  memberIds: string[]
  adminIds:  string[]
  createdAt: string
}