SDK 下载链接
配套使用 TRTC SDK 定制化版本,需要在 Podfile 中增加指定版本的 TRTC 依赖:
pod 'TXLiteAVSDK_TRTC', :podspec => 'https://liteav.sdk.qcloud.com/pod/liteavsdkspec/customer/TXLiteAVSDK_TRTC_shuziren_13.0.20262.podspec'
1. Virtualman.initSDK 参数配置接口
func initSDK(params: VirtualmanParams)
配置 SDK 鉴权参数,不建流。调用后即可使用
listSessionOfUin / listSessionOfProjectid / listSessionOfAssetVK 等查询接口。注意:
initSDK 仅做参数存储,不会发起网络请求。实际建流请调用 open(completion:) 或 openByAsset(completion:)。VirtualmanParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
appkey | String | 必要参数 | 数智人 key,通过交互数智人平台创建的数智人的标识 appkey |
accesstoken | String | 必要参数 | 数智人 accessToken,通过交互数智人平台创建的数智人的 accessToken |
serverDomain | String | 可选参数 | 服务器域名,不带协议头。默认值 "gw.tvs.qq.com"。私有化部署时填入对应域名。 |
disableTls | Bool | 可选参数 | 是否禁用 TLS 加密。默认 false(使用 https/wss),设为 true 则使用 http/ws。私有化部署时按需设置。 |
virtualmanProjectParams | VirtualmanProjectParams? | 可选参数 | Project 建流所需参数。配置后可调用 open 建流及 listSessionOfProjectid。 |
assetVirtualmanParams | AssetVirtualmanParams? | 可选参数 | Asset 建流所需参数。配置后可调用 openByAsset 建流及 listSessionOfAssetVK。 |
VirtualmanProjectParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
virtualmanProjectId | String | 必要参数 | 数智人项目 ID。 |
userId | String | 可选参数 | 用户的唯一标识,由调用方自己维护,以相同的 UserId 创建新流,会导致上一个该 UserId 流关闭。默认使用设备 identifierForVendor。 注意: 当使用 TRTC 协议时,该参数为数智人进房用户,调用方自身进房用户不能与该用户相同,如果相同会将数智人踢出房间,导致断流。 |
extraInfo | ExtraInfo? | 可选参数 | 建流扩展参数。 |
protocolOption | ProtocolOption? | 可选参数 | 用于配置外部 TRTC 应用。 |
AssetVirtualmanParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
assetVirtualmanKey | String | 必要参数 | 资产数智人 key(assetKey)。 |
userId | String | 可选参数 | 用户的唯一标识,由调用方自己维护,以相同的 UserId 创建新流,会导致上一个该 UserId 流关闭。默认使用设备 identifierForVendor。 注意: 当使用 TRTC 协议时,该参数为数智人进房用户,调用方自身进房用户不能与该用户相同,如果相同会将数智人踢出房间,导致断流。 |
extraInfo | ExtraInfo? | 可选参数 | 建流扩展参数。 |
protocolOption | ProtocolOption? | 可选参数 | 用于配置外部 TRTC 应用。 |
ExtraInfo 参数说明(可选)
参数名称 | 数据类型 | 参数类型 | 说明 |
alphaChannelEnable | Bool | 可选参数 | 是否开启透明通道。默认值 false。 |
ProtocolOption 参数说明(可选,用于配置外部 TRTC 应用)
参数名称 | 数据类型 | 参数类型 | 说明 |
trtcUseExternalApp | Bool? | 可选参数 | 是否使用外部 TRTC AppId,如果不使用,将使用数智人平台统一的 TRTC AppId。 注意: 数智人平台统一的 TRTC AppId,仅用于调试阶段,投产时,由用户自行在腾讯云申请 TRTC AppId。 |
trtcAppId | String? | 条件必填 | |
trtcRoomId | Int? | 条件必填 | TRTC 数字房间号。使用外部 TRTC AppId 时,trtcRoomId 和 trtcStrRoomId 必填其一。数字房间号最大值为4294967294。 注意: 要和 trtcAutoGenRoomIdType 的房间号类型匹配。 |
trtcStrRoomId | String? | 条件必填 | TRTC 字符串房间号。使用外部 TRTC AppId 时,trtcRoomId 和 trtcStrRoomId 必填其一。 注意: 要和 trtcAutoGenRoomIdType 的房间号类型匹配。 |
trtcAutoGenRoomIdType | Int? | 可选参数 | 房间号类型。0:数字类型,1:字符串类型,默认数字类型。 |
trtcUserSig | String? | 条件必填 | |
trtcPrivateMapKey | String | 可选参数 | TRTC 数智人用户权限票据。未开启高级权限控制可不填,默认填 "dummy"。 |
clientUserId | String | 条件必填 | 客户侧用户 ID。使用外部 TRTC AppId 时必填。 注意: 调用方自身进房用户,不能与数智人的 userId 相同,如果相同会将数智人踢出房间,导致断流。 |
clientUserSig | String? | 条件必填 | |
clientPrivateMapKey | String | 可选参数 | 客户侧用户权限票据。未开启高级权限控制可不填,默认填 "dummy"。 |
代码示例
let params = VirtualmanParams(appkey: Config.APP_KEY, accesstoken: Config.ACCESS_TOKEN)// 方式一:Project 建流let projParams = VirtualmanProjectParams(virtualmanProjectId: Config.VIRTUALMAN_PROJECT_ID)projParams.extraInfo = ExtraInfo(alphaChannelEnable: true)params.virtualmanProjectParams = projParams// 方式二:Asset 建流let assetParams = AssetVirtualmanParams(assetVirtualmanKey: Config.ASSET_VIRTUALMAN_KEY)assetParams.extraInfo = ExtraInfo(alphaChannelEnable: true)params.assetVirtualmanParams = assetParamsvirtualman.initSDK(params: params)
2. Virtualman.open 建流接口
2.1 通过 ProjectId 建流
func open(completion: @escaping (_ sessionId: String?, _ error: String?) -> Void)
通过数智人项目 ID 建流,ProjectId 从
initSDK 时配置的 VirtualmanProjectParams.virtualmanProjectId 中读取。建流完成后回调 completion:成功时 sessionId 有值、error 为 nil;失败时 sessionId 为 nil、error 包含错误信息。2.2 通过 AssetVirtualmanKey 建流
func openByAsset(completion: @escaping (_ sessionId: String?, _ error: String?) -> Void)
通过资产数智人 key 建流,assetVirtualmanKey 从
initSDK 时配置的 AssetVirtualmanParams.assetVirtualmanKey 中读取。回调同上。代码示例
// 方式一:通过 ProjectId 建流virtualman.open { sessionId, error inif let sessionId = sessionId {print("建流成功, sessionId: \\(sessionId)")} else {print("建流失败: \\(error ?? "unknown")")}}// 方式二:通过 AssetVirtualmanKey 建流virtualman.openByAsset { sessionId, error inif let sessionId = sessionId {print("建流成功, sessionId: \\(sessionId)")} else {print("建流失败: \\(error ?? "unknown")")}}
3. Virtualman.chat(_ params: ChatParams) 对话接口
用户发送文本,经平台 AI 处理后,数智人回答并播报。
ChatParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
text | String | 必要参数 | 对数智人要发送的文本。 |
isNewChat | Bool | 可选参数 | 是否开启新对话。默认值 false。 |
reqId | String | 可选参数 | 单次驱动的唯一标识, 32位的 UUID(不包含'-')。 注意: 每次发送都新生成一个 ReqId。默认自动生成。 |
videoSeiInfo | String? | 可选参数 | 需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。 |
代码示例
virtualman.chat(ChatParams(text: "你好", isNewChat: true))
4. Virtualman.sendText(_ params: TextParams) 纯文本驱动接口
直接控制数智人播报指定文本,不经过对话服务。
TextParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
text | String | 必要参数 | 纯文本驱动的内容。 |
reqId | String | 可选参数 | 单次驱动的唯一标识, 32位的 UUID(不包含'-')。默认自动生成。 |
videoSeiInfo | String? | 可选参数 | 需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。 |
代码示例
virtualman.sendText(TextParams(text: "要播报的文本"))
5. Virtualman.sendStreamText(_ params: StreamTextParams) 流式文本驱动接口
StreamTextParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
reqId | String | 必要参数 | 单次驱动的唯一标识。每一段流式文本指定一个32位 UUID 值(不包含'-')。 注意: 每一段流式文本序列指定一个 ReqId,而不是每一次请求指定一个。 |
text | String | 必要参数 | 流式文本内容,只需要发送增量的文本。每个片包字符串长度限制 2000 字节。 |
seq | Int | 必要参数 | 流式文本片包序号,序号必须从 1 开始。 |
isFinal | Bool | 可选参数 | 用于标记本次流式文本驱动是否结束,默认值 false。 注意: 当文本发送完毕后,需要再发送一个 isFinal=true 的驱动指令结束当次流式文本驱动。 |
isSentence | Bool | 可选参数 | 是否是子句模式,缺省值 false。为 true 服务端不会做重新组句。 |
isInsertSentence | Bool | 可选参数 | 是否是插入的子句,缺省值 false。为 true 并且是子句模式则表示当前分片需要插播。 |
videoSeiInfo | String? | 可选参数 | 需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。 |
6. Virtualman.sendAudio(_ params: AudioParams) 音频驱动接口
AudioParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
reqId | String | 必要参数 | 单次驱动的唯一标识。每一段音频指定一个32位 UUID 值(不包含'-')。 注意: 每一段流式音频序列指定一个 ReqId,而不是单独一次音频分片请求指定一个。 |
audio | String | 必要参数 | 音频原始数据的 Data,经 Base64 编码后的字符串。只支持: - 格式:PCM - 采样率:16kHz - 采样位深:16bits - 声道:单声道 |
seq | Int | 必要参数 | 音频片包序号,序号必须从 1 开始。 |
isFinal | Bool | 可选参数 | 用于标记本次音频驱动是否结束,默认值 false。 注意: 当数据包发送完毕后,必须再发送一个 isFinal=true 的空数据包(audio 字段填空串)结束当次音频驱动使数字人回到静默状态。 |
videoSeiInfo | String? | 可选参数 | 需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。 |
7. Virtualman.stop() 打断播报
在音频驱动、流式文本或非流式文本播报时,调用此接口用于打断当前播报。
支持的打断类型:
音频驱动打断:支持打断 sendAudio() 发起的音频驱动播报
流式文本打断:支持打断 sendStreamText() 发起的流式文本播报
普通文本打断:支持打断 sendText() 发起的文本播报
注意:
需要等到 WebSocket 下行消息返回 TextStart/AudioStart 标记后才可发送打断请求。
8. Virtualman.setSmartActionEnabled(_ value: Bool) 开启智能动作
设置是否开启智能动作,缺省值 false。为 true 并且输入的文本或者话术增强后的文本没有动作标签则会生成智能动作。
注意:
该设置与流绑定,需在
open / openByAsset 建流后调用。close 后再次 open 时需重新设置。9. Virtualman.setWsDelegate(_ delegate: VirtualmanWsDelegate?) WebSocket 事件监听
用于设置 WebSocket 连接生命周期事件的监听代理,感知连接状态变化。
VirtualmanWsDelegate 协议说明
方法 | 说明 |
onWsOpen() | WebSocket 连接已建立,此时可以发送消息。 |
onWsMessage(_ text: String) | 收到 WebSocket 下行消息(JSON 字符串)。 |
onWsClosed(code: UInt16, reason: String) | WebSocket 连接正常关闭。 |
onWsFailure(_ error: Error?) | WebSocket 连接异常断开。SDK 会自动尝试重连。 |
说明:
VirtualmanWsDelegate 所有方法均为可选实现(@objc optional)。
代码示例
class ViewController: UIViewController, VirtualmanWsDelegate {override func viewDidLoad() {super.viewDidLoad()virtualman.setWsDelegate(self)}func onWsOpen() {print("WebSocket 已连接,可以发送消息")}func onWsMessage(_ text: String) {// 处理下行消息}func onWsClosed(code: UInt16, reason: String) {print("WebSocket 已断开,等待自动重连")}func onWsFailure(_ error: Error?) {print("WebSocket 连接失败,等待自动重连")}}
10. Virtualman.setDelegate(_ delegate: VirtualmanDelegate?) TRTC 事件监听回调
用于设置 TRTC 事件监听代理。
VirtualmanDelegate 协议说明
方法 | 说明 |
onRecvSEIMsg(_ userId: String, message: Data) | |
onFirstVideoFrame(_ userId: String, streamType: Int32, width: Int32, height: Int32) | |
onError(_ errCode: Int32, errMsg: String?) | |
onConnectionLost() | TRTC 与云端的连接已经断开。 |
onTryToReconnect() | TRTC 正在尝试重新连接到云端。 |
onConnectionRecovery() | TRTC 与云端的连接已经恢复。 |
onNetworkQuality(localQuality: Int, remoteQuality: [Int]) | |
onStatistics(_ statistics: TRTCStatistics) |
说明:
VirtualmanDelegate 所有方法均为可选实现(@objc optional)。
11. Virtualman.statSession(callback:) 查询当前会话的状态
12. Virtualman.listSessionOfUin(callback:) 查询某个 uin 账号所有进行中的会话
13. Virtualman.listSessionOfProjectid(callback:) 查询数智人项目下的会话列表
用于查询当前数智人项目下的所有进行中的会话列表,调用
initSDK 后即可使用,无需建流。projectId 从 initSDK 时传入的 VirtualmanProjectParams.virtualmanProjectId 中读取;未配置时调用会返回错误提示。callback 返回值参考 查询数智人项目下的会话列表。virtualman.listSessionOfProjectid { result inprint(result)}
14. Virtualman.listSessionOfAssetVK(callback:) 查询个人资产形象下的会话列表
用于查询指定个人资产形象下的所有进行中的会话列表,调用
initSDK 后即可使用,无需建流。assetVirtualmanKey 从 initSDK 时传入的 AssetVirtualmanParams.assetVirtualmanKey 中读取;未配置时调用会返回错误提示。callback 返回值参考查询个人资产形象下的会话列表。virtualman.listSessionOfAssetVK { result inprint(result)}
15. Virtualman.sdkVersion 获取 SDK 版本号
let version = Virtualman.sdkVersion // 例:"1.1.0"
静态属性,无需实例化即可读取。
16. Virtualman.close() 数智人销毁接口
在页面销毁时或需要的时机调用关闭的方法以关闭数智人流,否则会占用后台资源。
注意:
Virtualman 在 deinit 时会自动调用 close()。但建议在明确不再使用时主动调用,不要依赖 deinit 时机。SDK 内部重连逻辑
1.
open 建流时,如果建流成功在轮询流状态过程遇到网络异常,有重试机制保证流能建立成功。如果超时失败,回调的 error 参数里会有对应的错误信息。2. WebSocket 自动重连:
SDK 内部监听 TRTC 的 onNetworkQuality 事件(每 2 秒触发一次),当检测到 WebSocket 断开且网络质量正常(1-5)时,自动触发重连。
心跳机制:SDK 每 45 秒发送一次心跳,如果发送失败会自动触发重连。
重连防重入:通过原子操作保证同一时刻只有一个重连请求在进行中。
终止条件:当收到 110014 错误码(流失效)时,停止重连和心跳。此时需要重新调用
open 建流。3. WebSocket 状态感知:通过
setWsDelegate 设置 VirtualmanWsDelegate,可实时感知连接状态变化(连接/断开/失败),用于 UI 提示用户当前是否可以交互。