507ce3d2ee
- 插件包改为 .xuqm.zip 事务制品，manifest/bundle/资源/SHA-256 统一校验 - 原生层拆分为桥接编排、插件包暂存、底层存储三个单一职责类 - 状态查询改为纯读取，不再误触发安装；新增 NATIVE_BASELINE_INCOMPATIBLE 拒绝 - SemVer 解析拆分为独立原生类并补原生测试 - XWebView 收口唯一内核，错误态统一中文层与重试 - common 增加请求头/运行时契约收口与 http 测试
79 行
3.3 KiB
Markdown
79 行
3.3 KiB
Markdown
# 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()
|
||
```
|
||
|
||
- `initialize(options)`：仅在不能使用配置文件自动初始化时调用。
|
||
- `awaitInitialization()`：等待唯一初始化完成；未配置且未手动初始化会抛出明确错误。
|
||
- `login(options)`：唯一登录入口；同一会话重复调用幂等，不同会话串行切换。
|
||
- `logout()`：唯一登出入口。
|
||
- `getUserId()` / `getUserInfo()`：只读获取当前会话。
|
||
|
||
不提供 `setUserInfo`、`setUserId` 或公开的配置文件初始化入口。
|
||
|
||
### 地址职责
|
||
|
||
- `platformUrl`：Xuqm 租户平台地址。远程配置、整包更新、插件 release set 检查等平台接口只使用该地址；自动配置未提供时使用 SDK 内置的公有平台地址。
|
||
- `apiUrl`：租户平台返回的业务扩展服务地址，只供明确声明使用该业务服务的扩展能力读取，不能替代 `platformUrl`。
|
||
- common 的 `apiRequest()` 默认基础地址在 SDK 初始化后固定为 `platformUrl`；访问其它业务服务时必须传绝对 URL 或在 common-only 模式显式 `configureHttp()`，禁止用远程 `apiUrl` 静默改写平台请求。
|
||
|
||
## common 通用能力
|
||
|
||
下列能力可以零初始化、零登录独立使用。`apiRequest` 未初始化时不会生成 SDK 签名头；可使用绝对 URL 或 `configureHttp` 设置基础地址。
|
||
|
||
- `apiRequest`、`configureHttp`、`useRequest`、`useApi`、`usePageApi`
|
||
- `expirationStatus`、`toTimestamp`、`millisecondsUntil`、`formatDateTime`
|
||
- `fileExists`、`ensureDirectory`、`readFileAsBase64`、`writeBase64File`、`openLocalFile`
|
||
- `decryptXuqmFile`、`hmacSha256Base64Url`
|
||
- `getDeviceId`、`getDeviceInfo`、`detectPushVendor`
|
||
- `showToast`、`showAlert`、`showConfirm`、`ScaledImage`
|
||
|
||
## 扩展包
|
||
|
||
- `@xuqm/rn-update`：`UpdateSDK`、`XuqmRuntime`、`definePlugin` 和 `xuqm-rn` CLI。
|
||
- `@xuqm/rn-xwebview`：`XWebViewView`、`XWebViewScreen`、JSBridge 与统一下载。
|
||
- `@xuqm/rn-bugcollect`：`BugCollect` 错误、事件、漏斗和队列上报。
|
||
- `@xuqm/rn-im`：在 common 会话含 `userSig` 且服务启用时连接。
|
||
- `@xuqm/rn-push`：在 common 会话变化时同步原生推送绑定。
|
||
|
||
所有扩展包都不提供第二套初始化或登录 API。
|
||
|
||
## update 插件检查边界
|
||
|
||
```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` 和进度回调控制。
|
||
- common HTTP 的统一默认请求上限为 30 秒；宿主需要更短的交互等待时显式传上述参数，不得在页面复制 `Promise.race` 或第二套超时器。
|
