本文档指导开发者通过License模式集成iOS SDK,实现设备管控和鉴权。多模态SDK需支持License计费模式,支持半托管和全托管两种接入模式。
1. 模式说明
使用 License 计费模式访问多模态交互开发套件需要集成 License SDK,请参考本文第 4 节集成 SDK。
1.1. 半托管模式
适用场景:客户自有云服务,能对自己的设备进行管理和鉴权,客户云服务和设备端有双向通信通道;
-
服务端开发:
- 参考云端接口开发说明 完成云端接口对接,设备计量管理服务提供设备注册和获取Token两个接口
-
设备端开发:
- 接入方通过本SDK的genRegisterReq接口获取设备注册签名。
- 拿到设备注册签名后调用接入方自有云端服务进行设备注册,接入方云端需集成POP SDK。
- 设备注册返回后调用本SDK的writeDeviceInfo接口写入设备信息。
- 调用本SDK的genGetTokenReq接口获取访问令牌信息的数据签名。
- 调用本SDK的getToken获取解签后业务交互令牌信息,之后可使用令牌信息进行业务交互。
1.2. 全托管模式
适用场景:客户没有云服务,无法对设备进行管理,由阿里云进行设备管理和鉴权
-
服务端开发:
- 无
-
设备端开发
- 调用本SDK的deviceRegister接口执行设备注册。
- 调用本SDK的getToken接口获取业务交互令牌,之后可使用令牌信息进行业务交互。
2. 使用前注意需了解事项
- 使用License模式前在百炼控制台创建了应用,并购买了License。
- SDK中封装了设备唯一标识生成逻辑并存储到keychain,避免同1设备重复注册,通过DeviceInfoUtils.shared.getDeviceId()调用,请务必使用SDK中获取deviceName接口逻辑或者接入方自行保证deviceName唯一性。
3. 接口说明
3.1. SDK初始化 initialize
半托管和全托管模式均需先执行初始化接口
入参:
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
appId | String | 是 | 应用标识,在百炼控制台创建应用之后会生成该ID |
appSecret | String | 是 | 应用密钥,在百炼控制台创建应用之后会生成该密钥 |
deviceName | String | 是 | 设备名称:(使用设备WIFI MAC或唯一序列号) |
callBack | InitCallBack | 是 | SDK初始化回调,参考InitCallBack对象 |
返回值 | 方法名 | 说明 |
|---|---|---|
void | success() | 初始化成功 |
void | fail(ResultError error) | 初始化失败 |
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | int | 否 | 返回错误码 |
message | String | 否 | 返回错误码说明 |
3.2. 半托管模式
3.2.1. 设备注册相关接口
3.2.1.1. 生成设备注册信息 genRegisterReq
入参:字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
appId | String | 是 | 应用标识,在百炼控制台创建应用之后会生成该ID |
deviceName | String | 是 | 设备名称:(使用设备WIFI MAC或唯一序列号) |
payMode | String | 是 | 计费方式:PAYG(后付费)、LICENSE(license计费) |
reqNonce | String | 是 | 请求随机串,长度26位 |
requestTime | String | 是 | 请求时间 |
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
success | boolean | 是 | 请求处理是否成功 |
code | int | 否 | 请求失败code |
message | String | 否 | 请求失败描述 |
data | String | 否 | 设备注册调用POP接口所需的签名参数 |
3.2.1.2. 写入设备注册信息 writeDeviceInfo
调用云端设备注册的pop接口得到的响应,需要再次传回设备端SDK,进行信息写入 入参:字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
appId | String | 是 | 应用标识,在百炼控制台创建应用之后会生成该ID |
deviceName | String | 是 | 设备名称:(使用设备WIFI MAC或唯一序列号) |
reqNonce | String | 是 | 请求发起随机串,长度26位 |
rspNonce | String | 是 | 返回数据的随机串,长度26位 |
responseTime | String | 是 | 返回数据的时间戳 |
signature | String | 是 | YOUR_SIGNATURE |
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
success | boolean | 是 | 请求处理是否成功 |
code | int | 否 | 请求失败code |
message | String | 否 | 请求失败描述 |
data | String | 否 | 设备注册调用POP接口所需的签名参数 |
3.2.2. 获取业务交互令牌相关接口
3.2.2.1. 生成获取访问令牌信息 genGetTokenReq
入参:字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
nonce | String | 是 | 请求随机串,长度26位 |
appId | String | 是 | 应用标识,在百炼控制台创建应用之后会生成该ID |
deviceName | String | 是 | 设备名称:(使用设备WIFI MAC或唯一序列号) |
payMode | String | 是 | 计费方式:PAYG(后付费)、LICENSE(license计费) |
tokenType | String | 是 | 请求令牌的类型(当前仅支持MMI类型) MMI:多模态交互令牌 |
requestTime | String | 是 | 请求时间戳,单位ms |
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
success | boolean | 是 | 请求处理是否成功 |
code | int | 否 | 请求失败code |
message | String | 否 | 请求失败描述 |
data | String | 否 | 设备注册调用POP接口所需的签名参数 |
3.2.2.2. 解签POP接口返回的token数据 getToken
入参:字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
appId | String | 是 | 应用标识,在百炼控制台创建应用之后会生成该ID |
deviceName | String | 是 | 设备名称:(使用设备WIFI MAC或唯一序列号) |
reqNonce | String | 是 | 请求随机串,长度26位 |
rspNonce | String | 是 | 返回数据的随机串,长度26位 |
responseTime | String | 是 | 返回数据的时间戳 |
signature | String | 是 | YOUR_SIGNATURE |
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
success | boolean | 是 | 请求处理是否成功 |
code | int | 否 | 请求失败code |
message | String | 否 | 请求失败描述 |
data | String | 否 | 返回解签后的数据 |
3.3. 全托管模式
3.3.1. 检查设备是否注册 deviceIsRegistered
入参:
无
出参:
设备是否注册
调用示例:
3.3.2. 设备注册 deviceRegister
入参:
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
params | Object | 是 | 设备注册入参对象,参考DeviceRegisterParams对象 |
callBack | DeviceRegisterCallBack | 是 | 设备注册回调 |
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
nonce | String | 是 | 请求随机串,长度26位 |
appId | String | 是 | 应用标识,在百炼控制台创建应用之后会生成该ID |
workspaceId | String | 否 | 工作空间ID,使用工作空间额度注册才需要 |
deviceName | String | 是 | 设备名称:(使用设备WIFI MAC或唯一序列号) |
requestTime | String | 是 | 请求时间 |
payMode | String | 是 | 计费方式:PAYG(后付费)、LICENSE(license计费) |
3.3.3. 获取业务交互令牌 getToken
入参:
字段 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
params | Object | - | 是 | 设备认证所需参数对象,参考GenGetTokenParams对象 |
callBack | GetTokenCallBack | - | 是 | 获取token回调,参考GetTokenCallBack 对象 |
字段 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
nonce | String | - | 是 | 16字节随机数(26字符) |
appId | String | - | 是 | 应用标识,在百炼控制台创建应用之后会生成该ID |
apiKey | String | - | 是 | 应用密钥,在百炼控制台密钥管理创建 |
deviceName | String | - | 是 | 设备唯一标识 |
requestTime | String | - | 是 | 请求时间戳(ms) |
payMode | String | - | 是 | 计费方式:PAYG(后付费)、LICENSE(license计费) |
tokenType | String | - | 是 | 请求令牌的类型(当前仅支持MMI类型) MMI:多模态交互令牌 |
3.4. 获取License标识签名
入参:
字段 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
params | Object | - | 是 | 设备认证所需参数对象,参考LicenseSignatureParams对象 |
字段 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
appId | String | - | 是 | 应用标识,在百炼控制台创建应用之后会生成该ID |
deviceName | String | - | 是 | 设备唯一标识 |
taskId | String | - | 是 | 本次连接唯一标识,用于在工程链路上跟踪任务执行。由客户端生成,格式建议为36位uuid字符串,格式示例:"f894c16f-f20e-4c1d-837e-89e0fbc63a43" |
字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
timestamp | String | - | 当前时间戳ms |
license_info | String | - | license_info签名信息 |
device_info | String | - | device_info签名信息 |
3.5. 设备重置 deviceReset
tips: 在百炼控制台重置设备后,需要调用SDK deviceReset接口重置设备,方可进行重新注册。
入参:
无
出参:
Boolean 是否重置成功
调用示例:
4. 集成依赖库
使用最新版本 iOS SDK,引用其中的MultimodalDialogTongyiMetathings.framework
5. 涉及多模态SDK接入修改
- 在启动会话前完成tongyimetathings SDK的初始化和检测设备是否注册,未注册执行设备注册,具体参考接入示例工程。
- 初始化该SDK,设备注册完成后获取多模态会话token,参考上述2.1,2.3接口,将getToken接口返回的dashToken数据设置为apiKey,具体参考示例工程。
- 创建会话时传入license计费标识,参考接入示例: