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

XuqmGroup RN SDK API

公共生命周期

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 插件检查边界

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 或第二套超时器。