设备激活与续费
先由管理员生成购买凭证,再由设备联网领取绑定本机 SN 的 License。设备 SDK 完成本地验签、保存和时间检查,授权有效后才能进行可视对讲。
按本页完成授权后,再按 Android SDK 接入指南 连接 MQTT。业务系统还需将设备 UUID 绑定到租户,设备 UUID 须与授权使用的 SN 一致。
激活和续费时序
1. 准备授权服务和设备信息
- 为设备提供可访问的 HTTPS 授权地址。平台首次启动生成签名私钥,运维需持久化并备份签名私钥及激活凭证加密密钥,平台升级时继续使用原文件。
- 登录管理后台进入「设备授权」,点击「下载设备公钥」。将导出的 PEM 公钥预置到设备应用或固件中。
-
确定产品型号,例如
RTC-BOX,保证后台购买记录和设备配置完全一致。 -
从可信系统或固件读取设备 SN,保留大小写和前导零。Android 默认优先读取
Build.SERIAL,必要时使用Build.getSerial()或集成方提供的固件接口。
授权地址、公钥和产品型号由产品集成时配置。设备通过自己的 SN 领取授权,年限由平台购买记录确定。
2. 后台生成激活凭证
进入「设备授权 → 购买(生成)记录」,点击「生成激活码」。管理员确认购买后填写表单并生成凭证。
- 类型
- 首次激活选择 ACTIVATE。已有该产品授权的设备续费选择 RENEW,已过期设备也可续费。
- 年限
- 必填,1~100 年。平台按 UTC 日历年计算期限。
- 产品型号
- 必填,与设备初始化授权模块时的 productCode 一致。使用 1~64 位字母、数字、下划线或短横线。
- 绑定 SN
- 首次激活可选,留空时绑定到首次激活成功的设备。续费必填,填写已有授权的原设备 SN,格式与产品型号相同。
- 客户
- 可选,最多 128 字符,方便管理员查找交付对象。
- 备注
- 可选,最多 500 字符,用于记录购买和交付说明。
生成后,将弹窗中的激活码或二维码交付给客户。在购买列表中点击「激活码 / 二维码」可再次查看和下载二维码。每条购买记录对应一份权益,两种凭证任选一种使用。
「设备 SN」查询框按完整 SN 精确查询,购买列表可查到预绑定或实际激活的 SN。
3. 设备联网激活
设备通过 HTTPS 调用
POST /api/v1/device-licenses/redeem
。Android SDK 自动读取本机 SN、生成并保存请求编号,宿主传入购买凭证即可。
| 参数 | 用途 | 要求 |
|---|---|---|
| requestId | 本次激活请求编号 | 1~64 位字母、数字、下划线或短横线,重试保留原值,SDK 自动管理。 |
| deviceSn | 授权绑定的设备 SN | 从本机读取,1~64 位字母、数字、下划线或短横线。 |
| productCode | 产品型号 | 与后台购买记录一致,格式与 SN 相同。 |
| activationCode | 购买的激活码 | 与 qrContent 二选一,最多 128 字符。 |
| qrContent | 扫码硬件读取的二维码原文 | 与 activationCode 二选一,以 LIC1. 开头,最多 4096 字符,设备直接上传原文。 |
{
"requestId": "device-activation-001",
"deviceSn": "RTC-000123",
"productCode": "RTC-BOX",
"activationCode": "<购买的激活码>"
}
成功响应直接包含
orderRef
、
license
、
expiresAt
和
serverTime
。平台核对产品、SN、购买状态和历史授权,签发结果、购买状态与成功激活记录在同一事务中提交。
设备使用预置公钥校验返回 License 的签名,再核对本机 SN 和生效时间。SDK 原子保存 License,并按有效期返回 ACTIVE 或 EXPIRED。网络、验签或存储失败时保留原授权。
4. Android 初始化与授权检查
授权模块随
intercom-core-android
提供,设备 MQTT SDK 会传递引入。以下变量由宿主初始化,
publicKeyPem
为后台导出的公钥原文。
DeviceLicenseClient license = new DeviceLicenseClient(applicationContext, "https://license.example.com", "RTC-BOX", publicKeyPem, false);
DeviceLicenseClient.Callback callback = new DeviceLicenseClient.Callback() {
@Override
public void onSuccess(LicenseVerifier.Claims claims) {
updateLicenseDisplay(license.getLicenseStatus(), claims.expiresAt);
}
@Override
public void onFailure(String code, String message) {
showActivationError(code, message);
}
};
// 输入激活码后调用。
license.activateAsync(purchasedActivationCode, callback);
// 扫码硬件获得原文后调用此入口。
license.activateQrAsync(scannedQrContent, callback);
激活码和扫码入口按实际凭证选择一次调用。回调在主线程,宿主根据
getLicenseStatus()
更新界面。固件需要专用 SN 接口时,可使用带
Supplier<String>
的构造方法。
| 授权状态 | 宿主处理 |
|---|---|
| NOT_ACTIVATED | 提示输入激活码或扫码,完成联网激活。 |
| ACTIVE | 授权有效,可以发起和受理对讲。 |
| EXPIRED | 提示购买续费凭证并激活。 |
| INVALID_LICENSE | 检查预置公钥和本机 SN,或使用原凭证联网重新领取。授权撤销时联系管理员。 |
| CLOCK_UNTRUSTED | 联网调用 refreshAsync(callback) 恢复授权和可信时间。 |
将授权实例传给设备配置后,SDK 会在发起和受理呼叫前、通话期间检查授权。完整通话代码见 设备 MQTT 初始化示例 。
5. 续费、重试与重启校时
- 续费时生成绑定原 SN、相同产品型号的 RENEW 购买记录,将新激活码或二维码再次交给设备的激活入口。
- 到期前续费从原到期时间增加购买年限,到期后续费从平台当前时间增加年限。闰日加年遇到非闰年时落在 2 月最后一天。
- 重复提交同一购买凭证会取回该笔购买的原 License,期限只增加一次。网络中断或本地保存失败时使用原凭证重试。
- 同一次开机内,SDK 使用平台时间与单调时钟校验有效期。设备重启或无法确认开机标识时,先调用 refreshAsync 完成联网校时。
- 校时优先重试未完成的激活请求。如果新凭证被明确拒绝,SDK 会尝试用此前保存的原凭证恢复授权和时间。设备授权已撤销时返回对应错误。
- 恢复出厂或丢失本地授权后,用最近一次购买凭证和原 SN 联网取回授权。授权过期会阻止新通话,并收尾进行中的通话。
if (license.getLicenseStatus() == LicenseVerifier.Status.CLOCK_UNTRUSTED) {
license.refreshAsync(callback);
}
6. 后台核对授权和激活记录
「已激活设备」按 SN、产品型号查看当前到期时间和撤销状态,可下载当前 License。「激活记录」保存每次请求的结果,包括重复领取、参数错误和签发失败;结合请求编号与购买记录编号定位问题。
需要提前签发时,在购买记录中点击「生成 License」,填写目标 SN。此操作会消费购买权益,设备随后使用该记录的激活码或二维码联网领取同一份 License。
- 激活设备的 SN
- 填写实际使用该权益的设备 SN。存在预绑定时必须一致,产品型号沿用该购买记录。
撤销购买记录会停止领取该记录的授权,撤销设备授权会停止该设备领取和续费。设备中已有的离线 License 可以使用至原到期时间,设备联网获知授权撤销后停止对讲。
| 错误标识 | 排查方法 |
|---|---|
| INVALID_REQUEST | 检查必填字段、长度和凭证是否二选一。 |
| CODE_INVALID / CODE_ALREADY_USED | 检查购买凭证、产品型号及凭证已绑定的 SN。 |
| DEVICE_MISMATCH | 检查本机 SN 与购买记录预绑定 SN。 |
| ALREADY_ACTIVATED / NO_BASE_LICENSE | 检查购买的是首次激活还是续费,同一产品的续费须有历史授权。 |
| REQUEST_CONFLICT | 同一请求编号的参数发生变化,恢复原请求或为新操作生成新编号。 |
| CODE_REVOKED / LICENSE_REVOKED | 联系授权管理员核对购买记录或设备授权。 |
| NETWORK_OR_STORAGE_ERROR / INVALID_LICENSE | 检查设备网络、私有存储、公钥和本机 SN,保留原凭证重试。 |
设备 Demo 可在「设备授权」中填写服务地址、产品型号和 PEM 公钥,保存后输入购买凭证,点击「联网激活 / 续费」。显示 ACTIVE 后再配置 MQTT 并测试呼叫。