XuqmGroup-AndroidSDK/sdk-update/README.md

# sdk-update

XuqmGroup Android SDK 更新模块。提供 App 版本检查和 APK 下载安装能力。

## 依赖

```kotlin
implementation("com.xuqm:sdk-update:VERSION")
implementation("com.xuqm:sdk-core:VERSION")  // 必须
```

## 快速开始

```kotlin
val result = UpdateSDK.checkAppUpdate(context)

if (result.status == UpdateCheckStatus.UPDATE_AVAILABLE) {
    val update = requireNotNull(result.update)
    UpdateSDK.downloadAndInstallApk(
        context,
        ApkInstallRequest(update.downloadUrl, update.versionCode, requireNotNull(update.apkHash)),
    )
}
```

## API

| API | 说明 |
|-----|------|
| `UpdateSDK.checkAppUpdate(context, bypassIgnore)` | 检查 App 更新 |
| `UpdateSDK.downloadApk(context, request, onProgress)` | 只下载并校验，可选额外保存到系统 Downloads |
| `UpdateSDK.installDownloadedApk(context, versionCode, sha256)` | 安装当前检查已授权且校验通过的 APK |
| `UpdateSDK.downloadAndInstallApk(context, request, onProgress)` | 下载、校验并调起系统安装器 |
| `UpdateSDK.openStore(context, updateInfo)` | 优先打开设备商店，失败时使用平台通用下载页 |
| `UpdateSDK.setLoginUpdateListener(listener)` | 接收登录后自动补检结果 |

### UpdateCheckResult

```kotlin
data class UpdateCheckResult(
    val status: UpdateCheckStatus,
    val network: NetworkStatus,
    val update: UpdateInfo?,
    val errorCode: String?,
    val message: String?,
)
```

## 工作原理

- `downloadAndInstall` 将 APK 下载到 `getExternalFilesDir(null)`，通过 `FileProvider` 触发系统安装
- 安装所需 FileProvider 由依赖的 `sdk-core` 唯一声明，Update 不复制 Manifest 或 paths 资源
- 安装前依次校验 SHA-256、宿主 packageName 和 APK 签名证书；只允许安装本次检查授权的版本
- 下载任务取消或进程退出后删除 `.part`，下次启动不会自动继续
- `PUBLIC_DOWNLOADS` 仅额外导出已校验 APK，不改变 SDK 私有安装源
- 支持 WebSocket 实时推送更新通知
- 是否要求登录由租户平台配置决定；要求登录时返回 `LOGIN_REQUIRED`，不抛错、不阻断宿主
- `network` 只提供当前网络事实，是否允许蜂窝网络下载完全由宿主决定
- 账号切换会取消旧会话检查并清理灰度判断缓存，新会话只自动补检一次