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

# 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)