XuqmGroup React Native SDK 文档

TypeScript · React Native 0.76+ · 发布至 Nexus npm rn-sdk 为内部基础包，业务方正常接入时使用 rn-common 和各业务模块即可。

安装

rn-common 可以独立使用；rn-im / rn-push / rn-update 会自动带上 rn-common 和 rn-sdk；rn-sdk 是内部基础包，不建议业务方直接引用。

# 基础能力
npm install @xuqm/rn-common
# 或
yarn add @xuqm/rn-common

# 单独接入某个业务模块时，`rn-common` 会作为依赖自动安装
npm install @xuqm/rn-im
npm install @xuqm/rn-push
npm install @xuqm/rn-update

# 依赖安装（peerDependencies）
npm install @react-native-async-storage/async-storage

目录结构

XuqmGroup-RNSDK/src/
├── core/
│   ├── http.ts         # fetch HTTP 客户端，AsyncStorage Token
│   └── sdk.ts          # XuqmSDK 初始化入口
├── im/
│   └── imClient.ts     # WebSocket IM 客户端，指数退避重连
├── push/
│   └── pushSDK.ts      # 推送 Token 注册
├── update/
│   └── updateSDK.ts    # 检查更新 / 下载 Bundle
└── index.ts            # 统一导出

---

快速开始

1. 初始化（App 入口）

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

await XuqmSDK.init({
  appKey: 'ak_your_app_key',
  debug: __DEV__,
})

2. 用户登录后设置 Token

await XuqmSDK.setToken('eyJ...')
// 登出时
await XuqmSDK.setToken(null)

Token 持久化存储于 AsyncStorage，App 重启后自动恢复。

---

HTTP 客户端

import { apiRequest } from '@xuqm/rn-common'

// 自动附加 Bearer Token
const data = await apiRequest<UserInfo>('/api/user/profile')
const result = await apiRequest<LoginResp>('/api/auth/login', {
  method: 'POST',
  body: { account, password },
})

---

IM 模块

ImClient

import { ImClient, MsgType, ChatType } from '@xuqm/rn-im'

const im = new ImClient()

im.on('connected', () => console.log('IM 已连接'))
im.on('disconnected', (code, reason) => console.log('断开', code))
im.on('message', (msg) => {
  console.log('新消息', msg.content)
  // msg: ImMessage
})
im.on('revoke', ({ msgId, operatorId }) => {
  console.log('消息被撤回', msgId)
})
im.on('error', (err) => console.error(err))

// 连接
im.connect()

// 发送消息
im.send({
  toId: 'user_002',
  chatType: ChatType.SINGLE,
  msgType: MsgType.TEXT,
  content: 'Hello from RN!',
})

// 撤回
im.revoke('msg-uuid')

// 组件卸载时断开
useEffect(() => {
  im.connect()
  return () => im.disconnect()
}, [])

React Hook 封装示例

import { useEffect, useState, useRef } from 'react'
import { ImClient, ImMessage } from '@xuqm/rn-im'

export function useIm() {
  const [messages, setMessages] = useState<ImMessage[]>([])
  const [connected, setConnected] = useState(false)
  const imRef = useRef<ImClient | null>(null)

  useEffect(() => {
    const im = new ImClient()
    imRef.current = im
    im.on('connected', () => setConnected(true))
    im.on('disconnected', () => setConnected(false))
    im.on('message', (msg) => setMessages(prev => [...prev, msg]))
    im.connect()
    return () => im.disconnect()
  }, [])

  const send = (params: Parameters<ImClient['send']>[0]) =>
    imRef.current?.send(params)

  return { messages, connected, send }
}

ImMessage 结构

interface ImMessage {
  id: string
  fromId: string
  toId: string
  chatType: 'SINGLE' | 'GROUP'
  msgType: MsgType
  content: string
  extra?: string
  revoked: boolean
  createdAt: string
}

消息类型（MsgType）

enum MsgType {
  TEXT = 'TEXT',
  IMAGE = 'IMAGE',
  VIDEO = 'VIDEO',
  AUDIO = 'AUDIO',
  FILE = 'FILE',
  CUSTOM = 'CUSTOM',
  LOCATION = 'LOCATION',
  NOTIFY = 'NOTIFY',
  RICH_TEXT = 'RICH_TEXT',
  CALL_AUDIO = 'CALL_AUDIO',
  CALL_VIDEO = 'CALL_VIDEO',
  FORWARD = 'FORWARD',
}

自动重连

断线后指数退避重连：3s → 6s → 12s → ... → 最大 30s。调用 disconnect() 后停止。

---

推送模块

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

// 在获取到设备推送 Token 后调用（如小米、华为推送回调）
await PushSDK.registerToken({
  appId: 'ak_xxx',
  userId: 'user_001',
  vendor: 'XIAOMI',    // HUAWEI / XIAOMI / OPPO / VIVO / HONOR / APNS
  token: 'device_push_token',
})

---

版本管理模块

检查 App 更新

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

const result = await UpdateSDK.checkAppUpdate({
  appId: 'ak_xxx',
  platform: 'android',     // 'android' | 'ios'
  currentVersionCode: 10,
})

if (result.needsUpdate) {
  console.log(result.versionName, result.downloadUrl, result.forceUpdate)
}

检查 RN Bundle 热更新

const rnResult = await UpdateSDK.checkRnUpdate({
  appId: 'ak_xxx',
  moduleId: 'main',
  platform: 'android',
  currentVersion: '1.0.0',
})

if (rnResult.needsUpdate && rnResult.info) {
  const { downloadUrl, md5 } = rnResult.info
  // 下载 bundle，校验 md5，调用原生模块热加载
}

---

发版

# 确认 .npmrc 指向 https://nexus.xuqinmin.com/repository/npm-hosted/
# 登录 Nexus npm（首次）
npm login --registry=https://nexus.xuqinmin.com/repository/npm-hosted/

# 发版
npm publish

版本号在 package.json 的 version 字段维护。