89 行
3.1 KiB
Markdown
89 行
3.1 KiB
Markdown
# React Native SDK
|
||
|
||
XuqmGroup React Native SDK 由一个可独立使用的基础包和多个按需安装的扩展包组成。宿主只需
|
||
维护一份平台下发的配置文件，并在登录成功后同步一次会话；已安装的扩展包会共享这份配置
|
||
和会话状态。
|
||
|
||
## 选择需要的模块
|
||
|
||
| 包 | 用途 | 是否需要平台配置 |
|
||
| --- | --- | --- |
|
||
| `@xuqm/rn-common` | 网络、文件、时间、设备、通用 UI 与 API Hooks | 独立使用时不需要 |
|
||
| `@xuqm/rn-update` | Android 整包更新与 RN 插件更新 | 需要 |
|
||
| `@xuqm/rn-bugcollect` | JS 异常、原生崩溃、面包屑和自定义事件 | 需要 |
|
||
| `@xuqm/rn-xwebview` | 独立 WebView 页面、导航栏、权限、下载和宿主 Bridge | 使用页面能力时需要 |
|
||
| `@xuqm/rn-im` | 单聊、群聊、会话、好友和离线消息 | 需要，并需要登录 |
|
||
| `@xuqm/rn-push` | 厂商推送绑定、离线推送和免打扰 | 需要，并需要登录 |
|
||
|
||
只安装实际使用的模块。扩展包会声明对 `rn-common` 的依赖范围，不需要宿主再创建第二套
|
||
初始化器、网络层或用户 Store。
|
||
|
||
## 两种接入方式
|
||
|
||
### 只使用 Common
|
||
|
||
不放置 `.xuqmconfig`，也不包装 Metro：
|
||
|
||
```ts
|
||
import { configureHttp, apiRequest, expirationStatus } from '@xuqm/rn-common'
|
||
|
||
configureHttp({ baseUrl: 'https://api.example.com' })
|
||
const health = await apiRequest('/health', { skipAuth: true })
|
||
const certState = expirationStatus('2027-12-31T23:59:59+08:00')
|
||
```
|
||
|
||
这种模式不需要初始化和登录。
|
||
|
||
### 使用任意扩展包
|
||
|
||
1. 从租户平台下载当前应用的 `.xuqmconfig`。
|
||
2. 将唯一一份配置放到 `src/assets/config/`。
|
||
3. 使用 SDK 提供的 Metro 包装器。
|
||
4. 宿主隐私声明获得用户同意后调用一次 `setPrivacyConsent(true)`。
|
||
5. 宿主登录成功后调用一次 `XuqmSDK.login(...)`。
|
||
|
||
SDK 不要求页面逐层传递 AppKey、平台地址、用户 ID 或登录凭证。
|
||
|
||
## 最小示例
|
||
|
||
```js
|
||
// metro.config.js
|
||
const { getDefaultConfig } = require('@react-native/metro-config')
|
||
const { withXuqmConfig } = require('@xuqm/rn-common/metro')
|
||
|
||
module.exports = withXuqmConfig(getDefaultConfig(__dirname))
|
||
```
|
||
|
||
```ts
|
||
import { XuqmSDK } from '@xuqm/rn-common'
|
||
|
||
await XuqmSDK.setPrivacyConsent(true)
|
||
|
||
await XuqmSDK.login({
|
||
userId: 'user-001',
|
||
accessToken: 'host-access-token',
|
||
// 仅使用 IM 时传入：
|
||
userSig: 'im-user-signature',
|
||
})
|
||
```
|
||
|
||
## 默认行为
|
||
|
||
- 配置由构建工具自动发现，运行时没有手动初始化 API。
|
||
- 配置错误会阻断构建，避免生成安装后才无法初始化的包。
|
||
- 扩展服务初始化失败不会阻断宿主应用自身启动；具体操作会返回结构化状态或错误。
|
||
- Update、BugCollect 等服务是否启用由租户平台控制。
|
||
- Debug 不会自动检查更新，也不会自动上报 BugCollect。
|
||
- Common 独立模式不会访问 XuqmGroup 服务。
|
||
|
||
## 下一步
|
||
|
||
- [安装与自动配置](./setup)
|
||
- [Common 基础能力](./common)
|
||
- [会话与隐私授权](./session)
|
||
- [版本与插件更新](./update)
|
||
- [BugCollect](./bugcollect)
|
||
- [XWebView](./xwebview)
|
||
- [IM 接入](./im)
|
||
- [推送接入](./push)
|
