设备激活与续费

先由管理员生成购买凭证,再由设备联网领取绑定本机 SN 的 License。设备 SDK 完成本地验签、保存和时间检查,授权有效后才能进行可视对讲。

按本页完成授权后,再按 Android SDK 接入指南 连接 MQTT。业务系统还需将设备 UUID 绑定到租户,设备 UUID 须与授权使用的 SN 一致。

激活和续费时序

管理员生成激活凭证,设备用本机 SN 和凭证联网领取 License,平台事务校验并签发,设备验签后保存,检查授权并启用对讲。
激活码与加密二维码共用在线激活接口。每笔购买只增加一次授权期限,重试返回该笔购买的原签发结果。

1. 准备授权服务和设备信息

  1. 为设备提供可访问的 HTTPS 授权地址。平台首次启动生成签名私钥,运维需持久化并备份签名私钥及激活凭证加密密钥,平台升级时继续使用原文件。
  2. 登录管理后台进入「设备授权」,点击「下载设备公钥」。将导出的 PEM 公钥预置到设备应用或固件中。
  3. 确定产品型号,例如 RTC-BOX ,保证后台购买记录和设备配置完全一致。
  4. 从可信系统或固件读取设备 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 签发 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 并测试呼叫。