XuqmGroup-RNSDK/docs/SDK-API参考.md

# XuqmGroup RN SDK API

## 公共生命周期

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

await XuqmSDK.awaitInitialization()

await XuqmSDK.login({
  userId: 'user-id',
  accessToken: 'http-token',
  userSig: 'optional-im-credential',
  name: '姓名',
  phone: '手机号',
})

await XuqmSDK.logout()
```

- `awaitInitialization()`：等待唯一自动初始化完成；缺少平台签发配置或 Metro 集成时
  抛出明确错误。
- `login(options)`：唯一登录入口；同一会话重复调用幂等，不同会话串行切换。
- `setPrivacyConsent(consented)`：唯一隐私同意同步入口；扩展 SDK 不自行弹窗。
- `getInitializationState()`：返回 `idle / initializing / ready / degraded / failed` 及
  可选结构化错误。
- `logout()`：唯一登出入口。
- `getUserId()` / `getUserInfo()`：只读获取当前会话。

不提供 `initialize`、`setUserInfo`、`setUserId` 或公开的配置文件初始化入口。

### 地址职责

- `platformUrl`：Xuqm 租户平台地址。远程配置、整包更新、插件 release set 检查等平台接口只使用该地址；自动配置未提供时使用 SDK 内置的公有平台地址。
- `apiUrl`：租户平台返回的业务扩展服务地址，只供明确声明使用该业务服务的扩展能力读取，不能替代 `platformUrl`。
- common 的 `apiRequest()` 默认基础地址在 SDK 初始化后固定为 `platformUrl`；访问其它业务服务时必须传绝对 URL 或在 common-only 模式显式 `configureHttp()`，禁止用远程 `apiUrl` 静默改写平台请求。
- 配置中的 `signingKey` 是可被客户端提取的请求完整性材料，不代表用户身份或接口
  授权；敏感接口必须继续校验登录 `accessToken`，构建制品上传使用 Jenkins 发布
  Bearer。

## common 通用能力

下列能力可以零初始化、零登录独立使用。`apiRequest` 未初始化时不会生成 SDK 签名头；可使用绝对 URL 或 `configureHttp` 设置基础地址。

- `apiRequest`、`configureHttp`、`useRequest`、`useApi`、`usePageApi`
- `expirationStatus`、`toTimestamp`、`millisecondsUntil`、`formatDateTime`
- `fileExists`、`ensureDirectory`、`readFileAsBase64`、`writeBase64File`、`openLocalFile`
- `hmacSha256Base64Url`、`sha256Hex`
- `getDeviceId`、`getDeviceInfo`、`detectPushVendor`
- `showToast`、`showAlert`、`showConfirm`、`ScaledImage`

## 扩展包

- `@xuqm/rn-update`：`UpdateSDK`、`XuqmRuntime`、`definePlugin` 和 `xuqm-rn` CLI。
  原生最终恢复页使用 `UpdateSDK.resetToEmbedded()`；它只清理 Update SDK 私有
  Bundle/发布状态，不影响宿主账号、业务数据、BugCollect 或签名 SDK。
- `@xuqm/rn-xwebview`：根部一次挂载 `XWebViewHost`，业务使用
  `openWebView(config)` 打开全屏页面；`XWebViewView` 只用于内嵌浏览器。业务
  JSBridge 通过 `config.bridge` 注入，不属于 XWebView 自身协议。
- `@xuqm/rn-bugcollect`：`BugCollect` 错误、事件、漏斗和队列上报。
  Debug 单次联调使用 `BugCollect.sendTestErrorAndFlush()`，App 不调用
  `startCapture()`。
- `@xuqm/rn-im`：在 common 会话含 `userSig` 且服务启用时连接。
- `@xuqm/rn-push`：在 common 会话变化时同步原生推送绑定。

所有扩展包都不提供第二套初始化或登录 API。

## update 插件检查边界

Update 服务由平台远程配置 `features.update` 控制，缺失时默认关闭。显式调用
`checkAppUpdate`、`downloadApk`、`downloadAndInstallApp`、`checkPluginRelease` 或
`installPluginRelease` 时，关闭状态统一抛出 `UpdateDisabledError`，错误码为
`UPDATE_DISABLED`，且不会先访问网络或原生安装模块；自动启动检查会正常跳过。

```ts
const plan = await UpdateSDK.checkPluginRelease('buz1', {
  signal,
  timeoutMs: 5_000,
})

if (plan) {
  await UpdateSDK.installPluginRelease(plan, { signal, onProgress })
}

await UpdateSDK.checkAndInstallPlugin('buz1', {
  signal,
  checkTimeoutMs: 5_000,
  onProgress,
})
```

- `checkPluginRelease()` 只检查版本和兼容依赖闭包，不下载、不激活；`timeoutMs` 只约束检查请求。
- `installPluginRelease()` 只安装此前确认的计划；本地基线已变化时抛出 `StaleReleaseSetError`。
- `checkAndInstallPlugin()` 用于宿主自动进入插件的场景；`checkTimeoutMs` 只传给检查阶段，下载仍由 `signal` 和进度回调控制。
- release-set 请求固定包含 `appVersion`、`nativeApiLevel`、`nativeBaselineId`；缺少
  native baseline 时不发请求。服务端返回的插件候选必须具有平台 Ed25519
  `keyId/signature`，客户端在计划前和安装前验证不可变 manifest。
  候选响应的 ZIP `sha256` 以 `archiveSha256` 纳入签名，下载后继续以同一值校验归档。
- common HTTP 的统一默认请求上限为 30 秒；宿主需要更短的交互等待时显式传上述参数，不得在页面复制 `Promise.race` 或第二套超时器。