后台 SDK 接入

Java 17 后台 SDK 用于调用平台业务接口、验证回调签名和生成签名应答。

查看后台 SDK 下载 →

1. 开通租户并引入依赖

在平台配置业务回调 HTTPS 地址和租户 MQTT 参数,取得 tenantId、AppId 与 AppKey。将下载包中的 Maven 仓库导入内部仓库后,按下载版本引入依赖。

<dependency>
    <groupId>cn.koodle</groupId>
    <artifactId>webrtc-center-backend-sdk</artifactId>
    <version>对应版本</version>
</dependency>

2. 添加设备并同步绑定

业务系统登记设备时,先用后台 SDK 将设备 UUID 绑定到当前租户。平台从签名凭据识别租户。确认绑定成功后,设备才可完成 MQTT 上线对账并参与通话。

var credentials = new PlatformCredentials(tenantId, appId, appKey);
var client = new BusinessIntercomClient(URI.create(platformUrl), credentials);
var binding = client.bindDevice(deviceUuid);
if (!binding.successful() || !"ACTIVE".equals(binding.data().path("status").asText())) {
    throw new IllegalStateException("设备绑定失败");
}
操作平台接口成功状态
bindDevice(uuid)POST /internal/intercom/devicesACTIVE
unbindDevice(uuid)POST /internal/intercom/devices/unbindUNBOUND

两个接口的 JSON 正文均为 {"uuid":"device_001"}。SDK 自动为每次调用签名。重复绑定或解绑会返回相应状态,同一设备的增删应按顺序同步。

业务系统同步绑定,平台保存租户与 UUID 后,设备连接租户 Broker 并对账。解绑时平台结束活动通话并清理路由。
设备绑定是业务系统新增设备时的同步步骤。设备换租户时,由原租户先解绑,再由新租户绑定。

3. 创建通话和指定接听人

校验业务用户的设备访问权限后调用平台接口。App 呼出用 createCall。设备呼入时,裁决唯一接听人后用 assignAnswerer。

// 复用前面按租户初始化的客户端。
var result = client.createCall(requestId, userId, deviceUuid, "intercom", "videoAudio");

检查返回的实际通话状态,再把可加入的 callId 返回给 App。创建和指定操作重试时复用原 requestId 及业务参数,SDK 会重新生成签名。

4. 验签、处理回调和接入网关

平台发送签名回调,业务系统验签、核对租户、去重并持久化事件,返回签名 HTTP 204。
平台未收到有效签名确认时会重试。业务系统识别到重复事件后,仍按本次请求的签名上下文返回确认。
  1. 接收回调时保持原始路径、查询串和请求正文,用 BusinessCallback.verifyAndParse 验签,并核对租户。
  2. 按 eventId 去重,按 callId 和 revision 更新状态。处理 INTERCOM_CALL 时发起业务来电通知,处理 INTERCOM_STATE 时同步终态。
  3. 成功接收后,用 signNoContentAck() 返回带签名的 HTTP 204。App 的 HTTP 请求和 WSS 握手经业务网关校验及签名后转发。