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

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 静默改写平台请求。
配置只包含公开应用身份与平台地址，不携带 appSecret 或其它客户端长期认证秘密。敏感接口校验登录 accessToken，构建制品上传使用 Jenkins 发布 Bearer。

common 通用能力

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

apiRequest、configureHttp、useRequest、useApi、usePageApi
expirationStatus、toTimestamp、millisecondsUntil、formatDateTime
fileExists、ensureDirectory、readFileAsBase64、writeBase64File、openLocalFile
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 返回结构化 UPDATE_AVAILABLE / NO_UPDATE / LOGIN_REQUIRED / SERVICE_DISABLED / FAILED，同时携带 Android 当前网络事实；检查失败或登录门禁不会阻断宿主。下载、安装与插件操作在服务关闭时仍统一抛出 UpdateDisabledError，错误码为 UPDATE_DISABLED，且不会先访问网络或原生安装模块；自动启动检查会正常跳过。

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

5.0 KiB 原始文件 Blame 文件历史 Unescape Escape

XuqmGroup RN SDK API

公共生命周期

地址职责

common 通用能力

扩展包

update 插件检查边界

5.0 KiB

原始文件 Blame 文件历史