92 行
3.7 KiB
Markdown
92 行
3.7 KiB
Markdown
# sdk-core
|
||
|
||
XuqmGroup Android SDK 核心模块。提供 SDK 初始化、HTTP 请求、Token 管理、文件操作、通用工具。
|
||
|
||
## 依赖
|
||
|
||
```kotlin
|
||
implementation("com.xuqm:sdk-core:VERSION")
|
||
```
|
||
|
||
## 初始化
|
||
|
||
### 配置文件自动初始化
|
||
|
||
从租户平台下载签名的 `XUQM-CONFIG-V2` 文件，原样放入：
|
||
|
||
```text
|
||
app/src/main/assets/config/config.xuqmconfig
|
||
```
|
||
|
||
宿主不需要编写初始化代码，也不得修改、复制或自行生成该文件。SDK 先验证平台
|
||
Ed25519 签名，再解密引导配置。V1、未知 keyId、签名错误和包名不匹配均拒绝使用。
|
||
`serverUrl` 是签发配置中的唯一平台地址且必填，运行时没有默认地址或跨平台回退。
|
||
配置只包含公开应用身份与平台地址，不包含 `appSecret` 或其它客户端长期认证秘密。
|
||
|
||
只依赖 `sdk-core` 时不会注册初始化 Provider、申请通知权限或合并 FileProvider，
|
||
基础 HTTP、下载、摘要、MediaStore、时间和安全存储能力无需初始化或登录。引入扩展 SDK 后才由扩展
|
||
Manifest 合并唯一初始化 Provider。
|
||
|
||
## API
|
||
|
||
### XuqmSDK（全局单例）
|
||
|
||
| API | 说明 |
|
||
|-----|------|
|
||
| `XuqmSDK.awaitInitialization()` | 等待平台配置拉取（coroutine） |
|
||
| `XuqmSDK.isInitialized()` | 检查是否已初始化 |
|
||
| `XuqmSDK.initializationStatus` | `IDLE / INITIALIZING / READY / DEGRADED / FAILED` |
|
||
| `XuqmSDK.setPrivacyConsent(granted)` | 同步宿主隐私授权；SDK 不自行弹窗 |
|
||
| `XuqmSDK.setUserInfo(info)` | 设置用户信息，触发所有子模块登录 |
|
||
| `XuqmSDK.setUserInfo(null)` | 登出，触发全局登出 |
|
||
| `XuqmSDK.getUserId()` | 获取当前 userId |
|
||
| `XuqmSDK.getUserInfo()` | 获取当前用户信息 |
|
||
| `XuqmSDK.appKey` | 当前 appKey |
|
||
| `XuqmSDK.platformConfig` | 平台配置（init 后可用） |
|
||
| `XuqmSDK.bugCollectApiUrl` | Bug 收集服务地址（从平台配置获取） |
|
||
| `XuqmSDK.bugCollectEnabled` | 是否启用 Bug 收集上报 |
|
||
| `XuqmSDK.tokenStore` | Token 存储（Android Keystore + AES-256-GCM） |
|
||
| `NetworkMonitor.observe(context)` | 独立启动网络观察并返回当前状态 |
|
||
| `NetworkMonitor.status` | 网络状态 `StateFlow` |
|
||
|
||
### XuqmUserInfo
|
||
|
||
```kotlin
|
||
data class XuqmUserInfo(
|
||
val userId: String, // 必填
|
||
val userSig: String? = null, // IM 登录凭证（可选）
|
||
val name: String? = null,
|
||
val phone: String? = null,
|
||
val avatar: String? = null,
|
||
)
|
||
```
|
||
|
||
### TokenStore
|
||
|
||
基于统一的 `SecureStore` 持久化：密钥由 Android Keystore 生成且不可导出，
|
||
值使用 AES-256-GCM 加密并通过 namespace/key 关联数据认证。
|
||
|
||
```kotlin
|
||
XuqmSDK.tokenStore.saveToken("eyJ...")
|
||
val token = XuqmSDK.tokenStore.getToken()
|
||
XuqmSDK.tokenStore.clear()
|
||
```
|
||
|
||
### FileSDK
|
||
|
||
`FileSDK` 只保留无需初始化的本地下载、摘要与 MediaStore 能力。
|
||
依赖租户平台的上传和依赖 FileProvider 的打开文件能力属于独立 `sdk-file`，
|
||
统一通过 `PlatformFileSDK` 调用。
|
||
|
||
```kotlin
|
||
// 下载
|
||
val file = FileSDK.download(context, url, fileName, destination, notificationTitle, onProgress)
|
||
```
|
||
保存到公共 Downloads 时，Android 10+ 使用 MediaStore；Android 9 及以下由宿主按系统
|
||
规范申请 `WRITE_EXTERNAL_STORAGE`。SDK 不申请“所有文件访问权限”，也不执行 shell 命令。
|
||
|
||
`NetworkMonitor` 不要求 SDK 初始化。它只申请 `ACCESS_NETWORK_STATE`，不会为了细分
|
||
蜂窝网络代际申请电话或定位权限；系统不允许读取时稳定返回 `CELLULAR`。
|
||
平台配置成功后以加密方式保存七天 LKG。平台暂不可用且 LKG 有效时进入
|
||
`DEGRADED`；没有可用缓存时扩展能力返回结构化错误，宿主核心业务不受影响。
|
