XuqmGroup-Web/docs-site/docs/android/license.md

Android 授权管理（License SDK）

模块：com.xuqm:sdk-license · 最低 Android 版本：API 24 (Android 7.0)

License SDK 用于设备授权注册与验证，所有平台（Android / iOS / 鸿蒙）共用同一个 License Key。

---

快速接入

1. 添加依赖

// 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 文件。

LicenseSDK.checkLicense { isValid ->
    if (isValid) {
        // 授权通过，允许使用
    } else {
        // 授权失败，提示用户
    }
}

---

API 说明

checkLicense

检查设备授权状态。首次调用时自动完成：读取 License 文件 → 解密 → 注册/验证设备 → 缓存结果。

// 回调方式
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 重新注册

---

完整示例

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 会自动恢复正常。