导入 SDK
使用 cocoapods 导入
1. 安装 CocoaPods
在终端窗口中输入如下命令（需要提前在 Mac 中安装 Ruby 环境）：
sudo gem install cocoapods
2. 创建 Podfile 文件
进入项目所在路径，输入以下命令行之后项目路径下会出现一个 Podfile 文件。
pod init
3. 编辑 Podfile 文件
target 'IvhServerRenderApp' dopod 'IvhServerRenderSDK', :podspec => 'https://vhalign-1251316161.cos.ap-guangzhou.myqcloud.com/ivhsdk/lib/ios/ivhserverrendersdk/1.0.1/IvhServerRenderSDK.podspec'end
4. 更新并安装 SDK
在终端窗口中输入如下命令以更新本地库文件，并安装或更新 SDK
pod installpod update
下载 SDK 导入
1. 下载 SDK 并解压到本地。
2. 打开您的 Xcode 工程项目，选择要运行的 target , 选中 Build Phases 项。
3. 单击 Link Binary with Libraries 项展开，单击底下的“+”号图标去添加依赖库。
依次导入 IvhServerRenderSDK.framework、JSONModel.framework、SocketRocket.framework。
然后通过
#import "IvhServerRenderSDK/IvhSDK.h"
引用 SDK。
配置 App 权限
如果需要使用 SDK 的录音上传功能，需要在 App 的 Info.plist 中添加下面的配置：
Privacy - Microphone Usage Description，并填入麦克风使用目的提示语。
初始化 SDK
接口描述
传入交互数智人平台上获取的 appkey、accesstoken，以初始化 SDK。
/// 初始化SDK/// - Parameters:/// - appkey: 从交互数智人平台获取的 appkey/// - accesstoken: 从交互数智人平台获取的 accesstoken-(id)initWithAppKey: (NSString*) appkey accesstoken: (NSString*)accesstoken;
新建视频流
接口描述
用于新建视频流。请求方可自定义传入参数，通过接口获取视频流播放地址。
一个 SDK 实例对象建流成功后无法再次建流，即一个实例只维护一个 session 对象，希望重新建流可以关掉当前流，或者初始化另一个 SDK 对象。
/// 新建视频流/// - Parameters:/// - newSessionRequestPayload: 新建视频流参数/// - completionHandler: 结果回调-(void)newSession: (NewSessionRequestPayload*) newSessionRequestPayload completionHandler: (void(^)(NewSessionResponsePayload * newSessionResponsePayload, NSError *error))completionHandler;
若使用 trtc 协议推流，返回的流播放地址中包含了 trtc 鉴权所需的参数。官方 trtc 供调试使用，正式产品需要自行注册 trtc，并在建流时传入相关参数。
接口参数
NewSessionRequestPayload 请求参数说明：
参数名称 | 类型 | 必选 | 描述 |
SessionId | String | 是 | 会话唯一标识。 Saas 环境不允许传入，私有化环境可传入，不传入则由系统自动分配。 |
UserId | string | 是 | 用户的唯一标识，由调用方自己维护。以相同的 UserId 创建新流，会导致上一个该 UserId 流关闭。 |
Protocol | string | 否 | 视频流播放协议，缺省值：rtmp。 当前支持参数：rtmp、trtc、webrtc |
DriverType | int | 是 | 数智人驱动方式。 1：文本驱动； 2：语音驱动（变声）； 3：语音驱动（原声） |
ProtocolOption | ProtocolOption | 否 | 协议自定义参数 |
ExtraInfo | ExtraInfo | 否 | 扩展额外信息 |
ProtocolOption：
名称 | 类型 | 必选 | 描述 |
RtmpPushAddr | string | 否 | 当 Protocol 填写 rtmp 时，指定 rtmp 推流地址 |
TrtcUseExternalApp | boolean | 否 | 是否使用外部 trtc appid，如果不使用，将使用数智人平台统一的 trtc appid。 |
TrtcAppId | string | 否 | trtc appid（使用外部 trtc appid 时必填）。 |
TrtcRoomId | int | 否 | trtc 房间号（不指定则由云端分配房间号）。 |
TrtcUserSig | string | 否 | trtc 数字人用户签名（使用外部 trtc appid 时必填）。 |
TrtcPrivateMapKey | string | 否 | trtc 数字人用户权限密钥（使用外部 trtc appid 时必填）。 |
ExtraInfo：
名称 | 类型 | 必选 | 描述 |
UserInfo | string | 否 | 用户相关的初始化信息 |
NewSessionResponsePayload 返回参数说明：
名称 | 类型 | 必选 | 描述 |
SessionId | String | 是 | 会话的唯一标识 |
PlayStreamAddr | String | 否 | 格式为： rtmp://liveplay.ivh.qq.com/live/m789 |
开启会话
接口描述
客户端播放器在确认拉取到了视频首帧，需要请求本接口，后台收到此接口请求后开始播报剧本首句。如果不调用此接口，则后台将在建流 10s 后自动播报剧本首句。此接口一般用于文本播报/对话型数智人。
/// 开启会话/// - Parameters:/// - startSessionRequestPayload: 开启会话参数/// - completionHandler: 结果回调-(void)startSession: (StartSessionRequestPayload*) startSessionRequestPayload completionHandler: (void(^)(NSError *error))completionHandler;
接口参数
StartSessionRequestPayload 参数说明：
参数名称 | 类型 | 必选 | 描述 |
SessionId | String | 是 | 会话唯一标识。 |
推送文本指令
接口描述
用于发送文本驱动数智人。
/// 推送指令/// - Parameters:/// - commandRequestPayload: 推送指令参数/// - completionHandler: 结果回调-(void)command: (CommandRequestPayload*) commandRequestPayload completionHandler: (void(^)(CommandResponsePayload * commandResponsePayload, NSError *error))completionHandler;
接口参数
CommandRequestPayload 请求参数说明：
参数名称 | 类型 | 必选 | 描述 |
SessionId | String | 是 | 会话唯一标识。 |
Command | string | 是 | SEND_TEXT：发送文本。 |
Data | Data | 是 | 数据对象 |
Data：
名称 | 类型 | 必选 | 描述 |
Text | string | 否 | 需要播报的文本内容或提问的文本内容，缺省值："" 发送空串时打断数字人，发送非空串文本时驱动数智人播报。 |
Interrupt | boolean | 否 | 需配合交互数智人配置平台中话术配置功能使用，如果话术配置中未配置该文本，则发送新文本为全部打断，此参数不生效，如果配置了该文本为不可打断，则此参数传 true 是强制打断。默认为 false。 |
CommandResponsePayload 返回参数说明：
名称 | 类型 | 必选 | 描述 |
Type | int | 是 | 返回的数据类型。 1：输入文本。 2：播报内容。 3：播报状态。 5：风险控制提示。 7：由于当前播报句不可打断而被遗弃输入文本 |
SessionId | String | 是 | 视频流会话的唯一标识 |
Text | String | 否 | 当 Type 为 1、2、7 时有此字段。输入文本/播报文本 |
TextPro | String | 否 | 当 Type 为 2 时有此字段。用于播报的文本内容，包含 ssml 标签等 |
TextDisplay | String | 否 | 当 Type 为 2 时有此字段。用于展示在端上的文本内容。 |
Uninterrupt | bool | 否 | 当 Type 为 2 时有此字段。当前播报句是否可打断。 true：不可打断，false：可打断。 |
Muted | bool | 否 | 当 Type 为 2 时有此字段。播报当前句时是否关闭收音。 true：关闭，false：不关闭。 |
SpeakStatus | String | 否 | 当 Type 为 3 时有此字段。数智人状态。 speak_start：正在播报，speak_over：静默中。 |
SpeechId | int | 否 | 当 Type 为 2、3、5 时有此字段。数智人播报的内容 id，第一次播报为 1，后续每次播报+1。 |
InteractionType | String | 否 | 当 Type 为 2 时有此字段。特殊消息类型，可于配置平台自定义，常见类型有：弹窗、图片等。 |
InteractionContent | String | 否 | 当 Type 为 2 时有此字段。特殊消息内容，用于下发弹窗、图片等非文本类的特殊消息。 |
ChatStatus | int | 否 | 当 Type 为 2 时有此字段。当此字段为 4 时，代表对话剧本结束。其他值为正常对话中状态。 |
InterruptResult | int | 否 | 当 Type 为 1 时有此字段。仅在请求参数 Interrup 为 true 时需要关注此字段。 1 - 成功，2 - 失败。 |
InterruptMessage | String | 否 | 当 Type 为 1 时有此字段。仅在请求参数 Interrup 为 true 且打断失败时需要关注此字段。打断失败的原因。 |
推送指令（长连接）
接口描述
在流式音频输入驱动和需要获取数智人播报状态这两种场景下，需要和服务端建立长连接。可以通过长连接推送指令，以及获取数据（见后面“事件说明”部分）。
此 SDK 实现了录音并上传音频数据的功能，若希望自行实现，可以使用此接口推送数据。
/// 通过 commandchannel 推送指令，可以推送音频数据/// - Parameter commandRequestPayload: 推送指令参数-(void)commandChannel: (CommandRequestPayload*) commandRequestPayload;
接口参数
CommandRequestPayload 请求参数说明：
参数名称 | 类型 | 必选 | 描述 |
SessionId | String | 是 | 会话唯一标识。 |
Command | string | 是 | 推送的指令类型。 |
Data | Data | 是 | 数据对象 |
Data：
名称 | 类型 | 必选 | 描述 |
Text | string | 否 | 需要播报的文本内容或提问的文本内容，缺省值："" 发送空串时打断数字人，发送非空串文本时驱动数智人播报。 |
Audio | string | 否 | 音频原始数据的 byte 数组，经 Base64 编码后的字符串。格式：PCM，采样率：16kHz，采样位深：16bits，声道：单声道，传输速率：6400B/200ms 或 3200B/100ms |
Interrupt | boolean | 否 | 需配合交互数智人配置平台中话术配置功能使用，如果话术配置中未配置该文本，则发送新文本为全部打断，此参数不生效，如果配置了该文本为不可打断，则此参数传 true 是强制打断。默认为 false。 |
推送文本指令
Command 传入 SEND_TEXT，Data 中 Text 字段传入被推送的文本。
推送音频指令
Command 传入 SEND_AUDIO，Data 中 Audio 字段传入被推送的音频的 base64 编码字符串。
推送心跳指令
Command 传入 SEND_HEARTBEAT，Data 中 Text 字段传入文本 "PING"。
录音上传
接口描述
开始录音并推送到服务器。音频上传过程中，commandChannel 会不断返回音频识别的文本结果。
若应用场景是文本驱动的数智人，也可以使用 腾讯云实时语音识别产品和 SDK，实现功能更全面的语音识别，拿到识别文本后推送文本指令给服务器。
-(void)startRecordAudio;
停止录音
接口描述
停止录音，停止发送数据。
-(void)stopRecordAudio;
关闭会话
接口描述
关闭视频流，关闭成功后，清理 SDK 内部状态，可重新建流。
/// 关闭会话/// - Parameters:/// - closeSessionRequestPayload: 关闭会话参数/// - completionHandler: 结果回调-(void)closeSession: (CloseSessionRequestPayload*) closeSessionRequestPayload completionHandler: (void(^)(NSError *error))completionHandler;
因超时或者其它原因导致拉流中断后，可通过状态查询接口查看推流状态，若已中断或不存在，可以通过 clearSession 清理掉当前 sdk 中的 session，并重新建流。
/// 清理掉当前的session，在断流时调用一次，以避免因服务器BUG或者闲置超时等原因断流/// 但是SDK获取不到这个异常状态，认为流仍然在使用，导致无法重新建流-(void)clearSession;
接口参数
CloseSessionRequestPayload 请求参数：
参数名称 | 类型 | 必选 | 描述 |
SessionId | String | 是 | 会话唯一标识。 |
查询会话状态
接口描述
用于查询指定会话的当前状态。
/// 查询会话状态/// - Parameters:/// - statSessionRequestPayload: 查询会话状态参数/// - completionHandler: 结果回调-(void)statSession: (StatSessionRequestPayload*) statSessionRequestPayload completionHandler: (void(^)(StatSessionResponsePayload * statSessionResponsePayload, NSError *error))completionHandler;
接口参数
StatSessionRequestPayload 请求参数：
参数名称 | 类型 | 必选 | 描述 |
SessionId | String | 是 | 会话唯一标识。 |
StatSessionResponsePayload 返回参数：
参数名称 | 类型 | 必选 | 描述 |
SessionStatus | int | 是 | 流状态。1：进行中，2：已关闭或不存在 |
SpeakStatus | string | 否 | 数智人状态。speak_start：正在播报，speak_over：静默中。 |
查询会话列表
接口描述
用于查询当前 appkey 下的所有进行中的会话信息。
/// 查询会话列表/// - Parameter completionHandler: 结果回调-(void)listSession: (void(^)(ListSessionResponsePayload* listSessionResponsePayload, NSError *error))completionHandler;
接口参数
ListSessionResponsePayload 返回参数：
参数名称 | 类型 | 必选 | 描述 |
Sessions | Session | 是 | 会话列表数组 |
Session：
名称 | 类型 | 必选 | 描述 |
UserId | string | 是 | 用户的唯一标识 |
SessionId | string | 是 | 会话的唯一标识。 |
SessionStatus | int | 是 | 流状态。1：进行中，2：已关闭 |
DriverType | string | 是 | 数智人类型。1：文本驱动，2：语音驱动(变声)，3：语音驱动(原声)。 |
数智人配置参数查询
接口描述
查询 appkey 对应的数智人配置参数。
/// 数智人配置参数查询/// - Parameter completionHandler: 结果回调-(void)queryConfig: (void(^)(QueryConfigResponsePayload* queryConfigResponsePayload, NSError *error))completionHandler;
接口参数
QueryConfigResponsePayload 返回参数：
参数名称 | 类型 | 必选 | 描述 |
DriverTypes | int[] | 是 | 驱动类型。 1：文本驱动， 2：语音驱动(变声)， 3：语音驱动(原声)。 |
RepaySource | string | 是 | NLP 引擎类型。使用对话数智人会返回此字段。 |
更新数智人画面参数
接口描述
通过本接口更新数智人画面参数。
/// 更新数智人画面参数/// - Parameters:/// - configSessionRequestPayload: 更新数智人画面参数请求参数/// - completionHandler: 结果回调-(void)configSession: (ConfigSessionRequestPayload*) configSessionRequestPayload completionHandler: (void(^)(NSError *error))completionHandler;
接口参数
ConfigSessionRequestPayload 请求参数：
参数名称 | 类型 | 必选 | 描述 |
SessionId | string | 是 | 会话 id。 |
SpaceParam | SpaceParam | 是 | 空间信息 |
ImageParam | ImageParam | 是 | 形象信息 |
SpaceParam：
名称 | 类型 | 必选 | 描述 |
BackgroundUrl | string | 否 | 背景 URL 地址（小于 1M 大小，最好与输出分辨率对齐，否则会被拉伸填充）要求：jpg、jpeg、png（其他格式不支持），不传使用上次背景图 |
ImagePosition | float | 是 | 人物在背景图中的 X 位置，人物图片中轴居中 X 为 0，取值范围为[-0.5,0.5]，不可移出背景图范围，线性值。 |
ImagePositionVertical | float | 是 | 人物在背景图中的 Y 位置，人物图片贴底 Y 为 0，取值范围为[-0.5,0.25]，向下可以移出背景图，线性值。 |
ImageZoom | float | 是 | 人物相对于原始素材图的缩放比例，由缩放后的大小和原始人物素材图计算得到的缩放比例。 计算公式：缩放后人物图片的宽度/(预览区域背景宽度/目标分辨率宽度)/人物原始素材的宽度。建议取值范围[0.25,2]. |
ImageParam：
名称 | 类型 | 必选 | 描述 |
待补充，主要是 3D 形象参数
事件说明
当服务端通过长连接推送数据事，会触发 SDK 的事件。
可以通过实现 "IvhSDKDelegate" protocol 来获取 SDK 的事件消息。
收到服务端数据
事件描述
收到服务端的原始数据。
/// 获取到 commandChannel 推送的数据/// - Parameter data: 收到的数据-(void)onCommandChannelData: (CommandResponsePayload*) data;
事件参数
CommandResponsePayload 的数据结构见 “推送文本指令” 接口中的描述。
其中，根据数据中的 Type 字段，收到的数据主要含下面几种类型：
1：输入文本。
2：播报内容。
3：播报状态。
5：风险控制提示。
7：由于当前播报句不可打断而被遗弃输入文本
当 Type 为 2，即收到的数据是 “播报内容” 时，根据数据中的 InteractionType 字段，又分为下面几种播报内容类型：
NSString * const IvhInteractionTypeBubbleInfo = @"BubbleInfo";NSString * const IvhInteractionTypeImage = @"Image";NSString * const IvhInteractionTypeVideo = @"Video";NSString * const IvhInteractionTypePopup = @"Popup";NSString * const IvhInteractionTypeOptionInfo = @"OptionInfo";
不同的播报内容，InteractionContent 中会返回对应消息格式的数据。
为了方便使用，SDK 分别对各种消息类型也进行了事件封装，开发者可直接通过下面的各类消息 delegate 获取解析后的数据。
若希望自己解析消息，只实现 "onCommandChannelData" 方法即可。
输入文本消息
服务端会将收到的文本消息通过此事件返回，文本驱动的数智人在音频流式发送的过程中，会不断返回识别出的文本。
/// 收到输入文本消息/// - Parameter text: 输入文本-(void) onInputData: (NSString*) text;
输出文本消息
/// 收到输出文本消息/// - Parameter text: 输出文本-(void) onOutputData: (NSString*) text;
推荐气泡消息
/// 收到推荐气泡UI数据/// - Parameter tips: 推荐气泡列表-(void) onTipsData:(NSArray<NSString*>*) tips;
特殊消息-图片
/// 收到 特殊消息-图片/// - Parameter url: 图片url-(void) onImageData: (NSString*) url;
特殊消息-视频
/// 收到 特殊消息-视频/// - Parameter url: 视频url-(void) onVideoData: (NSString*) url;
特殊消息-选择
/// 收到 特殊消息-选择/// - Parameters:/// - style: 弹窗样式类型/// - title: 标题/// - options: 选择内容-(void) onOptionInfoData: (int) style title:(NSString*) title options:(NSArray<NSString*>*) options;
特殊消息-弹窗
/// 收到 特殊消息-弹窗/// - Parameters:/// - title: 标题/// - buttonText: 确认按钮文本/// - content: 长文本内容-(void) onPopupData: (NSString*) title buttonText: (NSString*) buttonText content: (NSString*) content;
因不可打断丢弃文本
/// 因不可打断丢弃文本/// - Parameter text: 被丢弃的文本-(void) onDiscardText: (NSString*) text;
数据收发出错事件
/// commandChannel 收/发数据出错/// - Parameter commandError: 错误信息-(void)onCommandChannelError: (NSError*) commandError;
错误码说明
在新建视频流、开启会话、查询会话等接口中，错误信息会随 error 的 code 属性返回。
代码 | 含义 | 措施 |
100000 | 系统内部错误 | 重试或联系管理员定位错误 |
100001/100003 | 请求参数错误（包括参数格式、类型等错误，缺少参数错误，必传参数没填） | 对照 API 协议核查参数格式、类型 |
100002 | 参数取值错误 | 对照 API 协议核查参数列表 |
100005 | 未授权操作 | 检查对请求的会话是否有操作权限 |
100008 | 超过配额限制 | 会话超过并发限制 |
100009 | 资源不存在 | 查看权限范围是否越权 |
110001 | 请求体超过最大限制 | 检查上传的音频是否过快、过大；文本是否过长 |
110002 | 已触发风险控制 | 对话数智人在风控开关开启时会暂停对话 |
110004 | speech 请求失败 | 重试或联系管理员定位错误 |
110005 | 记录已经存在 | 过快的重复请求 |
110006 | 记录不存在 | 请检查请求的会话是否存在 |
110007 | 数智人项目已过期 | 检查有效期 |
110008 | 视频流参数变更时图片下载失败 | 重试或检查背景图片体积是否过大 |
其它错误为客户端错误或者未知错误，以错误消息为准。
