165 行
4.2 KiB
Markdown
165 行
4.2 KiB
Markdown
|
# Android 授权管理（License SDK）
|
|||
|
|
|
|||
|
|
**模块**：`com.xuqm:sdk-license` · **最低 Android 版本**：API 24 (Android 7.0)
|
|||
|
|
|
|||
|
|
License SDK 用于设备授权注册与验证，所有平台（Android / iOS / 鸿蒙）共用同一个 License Key。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 快速接入
|
|||
|
|
|
|||
|
|
### 1. 添加依赖
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
// app/build.gradle.kts
|
|||
|
|
dependencies {
|
|||
|
|
implementation("com.xuqm:sdk-license:0.4.2")
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 放置 License 文件
|
|||
|
|
|
|||
|
|
从租户平台下载 `.xuqmlicense` 加密文件，放入 app 的 assets 目录：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
app/src/main/assets/xuqm/license.xuqm
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
SDK 会按以下顺序查找文件：
|
|||
|
|
1. `assets/xuqm/license.xuqm`
|
|||
|
|
2. `assets/xuqm/` 目录下第一个 `.xuqmlicense` 文件
|
|||
|
|
|
|||
|
|
### 3. 检查授权
|
|||
|
|
|
|||
|
|
SDK **无需手动初始化**，首次调用 `checkLicense()` 时自动读取并解密 License 文件。
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
LicenseSDK.checkLicense { isValid ->
|
|||
|
|
if (isValid) {
|
|||
|
|
// 授权通过，允许使用
|
|||
|
|
} else {
|
|||
|
|
// 授权失败，提示用户
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## API 说明
|
|||
|
|
|
|||
|
|
### checkLicense
|
|||
|
|
|
|||
|
|
检查设备授权状态。首次调用时自动完成：读取 License 文件 → 解密 → 注册/验证设备 → 缓存结果。
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
// 回调方式
|
|||
|
|
LicenseSDK.checkLicense { isValid ->
|
|||
|
|
// true: 授权通过 false: 授权失败
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 协程方式
|
|||
|
|
lifecycleScope.launch {
|
|||
|
|
val isValid = LicenseSDK.checkLicense()
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**内部逻辑**：
|
|||
|
|
1. 检查本地缓存（默认 10 分钟有效期）
|
|||
|
|
2. 缓存有效 → 直接返回 `true`
|
|||
|
|
3. 缓存过期或无缓存：
|
|||
|
|
- 有 Token → 调用验证接口
|
|||
|
|
- 无 Token 或验证失败 → 调用注册接口
|
|||
|
|
4. 网络异常且缓存曾成功 → 返回 `true`（离线模式）
|
|||
|
|
5. 网络异常且无缓存 → 返回 `false`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 设备唯一码
|
|||
|
|
|
|||
|
|
SDK 自动选择设备唯一码，优先级如下：
|
|||
|
|
|
|||
|
|
| 优先级 | 来源 | 稳定性 |
|
|||
|
|
|--------|------|--------|
|
|||
|
|
| 1 | ANDROID_ID | 同一签名 + 设备 + 用户不变，重装不变 |
|
|||
|
|
| 2 | 持久化 UUID | 首次生成后持久化存储 |
|
|||
|
|
|
|||
|
|
**保持不变**的场景：App 重启、App 重装（同一签名）、系统升级
|
|||
|
|
|
|||
|
|
**会变化**的场景：恢复出厂设置、更换签名重新安装
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 离线模式
|
|||
|
|
|
|||
|
|
SDK 支持离线使用：
|
|||
|
|
- 首次激活需要网络连接
|
|||
|
|
- 激活成功后，缓存有效期内（默认 10 分钟）可离线使用
|
|||
|
|
- 网络异常时，若缓存曾经成功验证，继续返回授权通过
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 数据存储
|
|||
|
|
|
|||
|
|
| 数据 | 存储方式 | 说明 |
|
|||
|
|
|------|----------|------|
|
|||
|
|
| deviceId | EncryptedSharedPreferences | AES-256 加密 |
|
|||
|
|
| token | EncryptedSharedPreferences | AES-256 加密 |
|
|||
|
|
| 授权状态 | EncryptedSharedPreferences | AES-256 加密 |
|
|||
|
|
| fallback UUID | SharedPreferences | ANDROID_ID 不可用时使用 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## AppKey 变更
|
|||
|
|
|
|||
|
|
当 License 文件中的 AppKey 与已存储的不一致时，SDK 会自动：
|
|||
|
|
1. 清除所有旧数据（Token、deviceId、状态）
|
|||
|
|
2. 使用新 AppKey 重新注册
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 完整示例
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
class MyApplication : Application() {
|
|||
|
|
override fun onCreate() {
|
|||
|
|
super.onCreate()
|
|||
|
|
// 无需初始化代码，SDK 自动读取 License 文件
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class MainActivity : AppCompatActivity() {
|
|||
|
|
override fun onCreate(savedInstanceState: Bundle?) {
|
|||
|
|
super.onCreate(savedInstanceState)
|
|||
|
|
setContentView(R.layout.activity_main)
|
|||
|
|
|
|||
|
|
LicenseSDK.checkLicense { isValid ->
|
|||
|
|
runOnUiThread {
|
|||
|
|
if (isValid) {
|
|||
|
|
// 进入主界面
|
|||
|
|
} else {
|
|||
|
|
Toast.makeText(this, "授权验证失败", Toast.LENGTH_LONG).show()
|
|||
|
|
finish()
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 常见问题
|
|||
|
|
|
|||
|
|
**Q: checkLicense 返回 false 怎么办？**
|
|||
|
|
A: 检查以下几点：
|
|||
|
|
- License 文件是否放在 `assets/xuqm/` 目录
|
|||
|
|
- 文件名是否为 `license.xuqm` 或以 `.xuqmlicense` 结尾
|
|||
|
|
- 设备是否有网络连接（首次激活需要网络）
|
|||
|
|
- License 是否已过期或被管理员禁用
|
|||
|
|
|
|||
|
|
**Q: 不同平台可以用同一个 License 吗？**
|
|||
|
|
A: 可以。所有平台共用同一个 AppKey，设备数量统一计算。
|
|||
|
|
|
|||
|
|
**Q: 设备被禁用后如何恢复？**
|
|||
|
|
A: 由租户管理员在租户平台的授权管理页面重新激活该设备，App 端无需额外操作，下次 `checkLicense` 会自动恢复正常。
|
