​
产品概述

百语实时语音对话 iOS SDK 是一款轻量级实时智能语音对话开发工具包。它封装了服务端连接、音频采集播放、对话控制等底层复杂逻辑，帮助开发者仅需 10 分钟即可为 iOS 应用快速集成高质量的智能语音交互能力。 本 SDK 基于 WebRTC 技术构建，深度对接百语平台的智能硬件，支持与智能体进行端到端的实时语音对话，适用于陪伴硬件、智能客服、语音助手、智能外呼等多种业务场景。

​
一、接入前提

  1. 使用本 SDK 前，需先在百语平台创建智能体（Agent，又称 Robot），并通过 API 方式完成发布。发布成功后，可获取该智能体对应的唯一标识 robotKey 和访问令牌 robotToken，二者是 SDK 与智能体建立语音通话的核心身份凭证。
  2. 凭证获取指引：请参考《语音通话接入准备工作》完成操作。
安全提示：robotKey 和 robotToken 属于核心敏感信息，请务必妥善保管，严禁在客户端硬编码或公开泄露，避免造成信息泄露及不必要的计费损失。

​
二、SDK 基础信息

​
2.1 SDK 获取与文件说明

SDK 以 Framework 形式分发，最新版本可从官方发布页下载，解压后核心文件为 BRAIVoiceRTCKit.framework。

​
2.2 兼容性说明

兼容项具体要求
系统版本iOS 13.0 及以上
设备架构仅支持真机 arm64 架构，不支持模拟器编译与运行
编译选项不支持 BitCode

​
三、SDK 快速集成

​
3.1 导入 SDK 到项目

  1. 解压已下载的 SDK 安装包，获取 BRAIVoiceRTCKit.framework 文件。
  2. 打开 Xcode 工程，右键点击工程名称，选择 Add Files to “工程名”…。
  3. 在弹出的文件选择框中，选中 BRAIVoiceRTCKit.framework，勾选 Copy items if needed，并在 Add to targets 中选择需要集成 SDK 的目标 Target，点击 Add 完成导入。

​
3.2 配置 Framework 依赖

  1. 在 Xcode 中选中项目 Target，切换到 General 标签页。
  2. 找到 Frameworks, Libraries, and Embedded Content 区域。
  3. 将 BRAIVoiceRTCKit.framework 的嵌入方式设置为 Embed & Sign。

​
3.3 配置系统权限

SDK 需要使用麦克风进行音频采集，因此必须在工程的 Info.plist 文件中添加麦克风权限声明：
  • 右键点击 Info.plist，选择 Add Row。
  • 键名选择 Privacy - Microphone Usage Description。
  • 值填写权限申请的具体业务理由（例如：需要使用麦克风与智能体进行语音交互）。

​
3.4 最简集成代码示例

以下代码展示了 SDK 核心功能的完整集成流程，包括初始化、启动/停止语音交互、打断播报、麦克风开关等基础能力。

​
1. 初始化语音交互管理器

在需要使用语音功能的页面控制器中，引入 SDK 头文件并初始化 BRAIVoiceRTCManager，同时设置代理以接收回调事件。 
#import <BRAIVoiceRTCKit/BRAIVoiceRTCKit.h>

@interface YourViewController () <BRAIVoiceRTCManagerDelegate>
@property (nonatomic, strong, nullable) BRAIVoiceRTCManager *rtcManager;
@end

@implementation YourViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    // 初始化语音交互管理器，传入从百语平台获取的身份凭证
    self.rtcManager = [[BRAIVoiceRTCManager alloc] initAIVoiceRTCWithKey:@"<your-robotKey>"
                                                                  token:@"<your-robotToken>"
                                                               userName:@"<your-userName>"];
    // 设置代理，接收 SDK 所有回调事件
    self.rtcManager.delegate = self;
}

​
2. 启动语音交互

在用户触发语音交互时（例如点击按钮），调用启动方法发起语音通话，并通过回调处理启动结果。 
- (void)startVoiceChatAction {
    NSLog(@"发起语音交互请求");
    __weak typeof(self) weakSelf = self;
    
    [self.rtcManager startVoiceChatCompleteCallBack:^(BOOL isSuccess, BRAIVoiceRTCError * _Nullable error) {
        __strong typeof(weakSelf) strongSelf = weakSelf;
        if (!strongSelf) return;
        
        if (isSuccess) {
            NSLog(@"语音交互启动成功");
        } else {
            NSLog(@"语音交互启动失败：%@", error.errorMessage ?: @"未知错误");
        }
    }];
}

​
3. 停止语音交互

在需要停止语音交互时，调用 SDK 停止语音交互方法，并在 block 回调中判断是否停止成功。 
- (void)stopVoiceChatAction {
    NSLog(@"发起停止语音交互请求");
    __weak typeof(self) weakSelf = self;
    
    [self.rtcManager stopVoiceChatCompleteCallBack:^(BOOL isSuccess, BRAIVoiceRTCError * _Nullable error) {
        __strong typeof(weakSelf) strongSelf = weakSelf;
        if (!strongSelf) return;
        
        if (isSuccess) {
            NSLog(@"语音交互停止成功");
        } else {
            NSLog(@"语音交互停止失败：%@", error.errorMessage ?: @"未知错误");
        }
    }];
}

​
4. 主动打断机器人播报

在机器人语音播报过程中，可调用打断方法主动终止播报，打断结果通过代理方法回调。 
- (void)interruptRobotAction {
    if (!self.rtcManager) {
        NSLog(@"打断失败：语音交互管理器未初始化");
        return;
    }
    
    NSLog(@"发起打断机器人播报请求");
    [self.rtcManager interrupt];
}

#pragma mark - BRAIVoiceRTCManagerDelegate
- (void)onVoiceRTCInterruptResult:(BOOL)isSuccess error:(BRAIVoiceRTCError *)error {
    if (isSuccess) {
        NSLog(@"机器人播报打断成功");
    } else {
        NSString *errorMsg = error.errorMessage.length > 0 ? error.errorMessage : @"未知错误";
        NSLog(@"机器人播报打断失败：%@", errorMsg);
    }
}

​
5. 麦克风开关控制

调用麦克风控制方法实现本地音频采集的开启与关闭，操作结果通过代理方法回调。 
- (void)toggleMicrophoneAction:(BOOL)isEnable {
    if (!self.rtcManager) {
        NSLog(@"麦克风操作失败：语音交互管理器未初始化");
        return;
    }
    
    NSLog(@"%@麦克风", isEnable ? @"开启" : @"关闭");
    [self.rtcManager setAudioEnable:isEnable];
}

#pragma mark - BRAIVoiceRTCManagerDelegate
- (void)onVoiceRTCSetAudioEnableResult:(BOOL)isSuccess enable:(BOOL)enable error:(BRAIVoiceRTCError *)error {
    NSString *operation = enable ? @"开启" : @"关闭";
    if (isSuccess) {
        NSLog(@"麦克风%@成功", operation);
    } else {
        NSString *errorMsg = error.errorMessage.length > 0 ? error.errorMessage : @"未知错误";
        NSLog(@"麦克风%@失败：%@", operation, errorMsg);
    }
}

​
四、SDK 核心 API 说明

所有核心方法均封装在 BRAIVoiceRTCManager 类中，调用前需确保实例初始化成功。

​
4.1 初始化语音交互管理器

- (instancetype)initAIVoiceRTCWithKey:(NSString *)robotKey
                                token:(NSString *)robotToken
                             userName:(NSString *)userName;
  • 功能说明：创建并初始化 BRAIVoiceRTCManager 实例，同时缓存身份凭证信息。
  • 参数说明：
    • robotKey：从百语平台获取的智能体唯一标识
    • robotToken：从百语平台获取的智能体访问令牌
    • userName：当前用户的业务唯一标识（用于日志排查和会话追踪）
  • 返回值：初始化后的 BRAIVoiceRTCManager 实例

​
4.2 启动语音会话

- (void)startVoiceChatCompleteCallBack:(BRAIVoiceChatResultBlock)resultBlock;
  • 功能说明：发起与智能体的实时语音会话，建立 RTC 音视频连接。
  • 参数说明：
    • resultBlock：启动结果回调，包含是否成功标识 isSuccess 和错误信息对象 error

​
4.3 结束语音会话

- (void)stopVoiceChatCompleteCallBack:(BRAIVoiceChatResultBlock)resultBlock;
  • 功能说明：主动结束当前语音会话，释放 RTC 连接资源。
  • 参数说明：
    • resultBlock：停止结果回调，包含是否成功标识和错误信息对象

​
4.4 打断机器人播报

- (void)interrupt;
  • 功能说明：主动打断机器人正在进行的语音回复和播报，打断结果通过 onVoiceRTCInterruptResult:error: 代理方法回调。

​
4.5 麦克风开关控制

- (void)setAudioEnable:(BOOL)enable;
  • 功能说明：开启或关闭本地麦克风音频采集，操作结果通过 onVoiceRTCSetAudioEnableResult:enable:error: 代理方法回调。
  • 参数说明：
    • enable：YES 表示开启麦克风，NO 表示关闭麦克风（本地静音）

​
4.6 获取 SDK 版本号

+ (NSString *)sdkVersion;
  • 功能说明：获取当前集成 SDK 的版本号字符串。
  • 返回值：SDK 版本号（例如：@"1.0.0"）

​
五、SDK 代理回调说明

所有回调方法均通过 BRAIVoiceRTCManagerDelegate 协议提供，需在初始化时设置 delegate 属性才能正常接收回调。

​
5.1 打断结果回调

- (void)onVoiceRTCInterruptResult:(BOOL)isSuccess error:(BRAIVoiceRTCError *_Nullable)error;
  • 触发时机：调用 interrupt 方法后触发。
  • 参数说明：
    • isSuccess：打断操作是否成功，成功为 YES，失败为 NO
    • error：错误信息对象，成功时为 nil，失败时包含具体错误码和描述

​
5.2 麦克风开关结果回调

- (void)onVoiceRTCSetAudioEnableResult:(BOOL)isSuccess enable:(BOOL)enable error:(BRAIVoiceRTCError *_Nullable)error;
  • 触发时机：调用 setAudioEnable: 方法后触发。
  • 参数说明：
    • isSuccess：麦克风开关操作是否成功
    • enable：本次操作的目标状态（与 setAudioEnable: 入参完全一致）
    • error：错误信息对象，成功时为 nil

​
5.3 运行时异常回调

- (void)onVoiceRTCRuntimeError:(BRAIVoiceRTCError *_Nonnull)error;
  • 触发时机：语音交互过程中发生未被其他回调覆盖的底层异常或运行时错误时触发。
  • 说明：不包含启动失败、停止失败、打断失败、麦克风开关失败等已单独回调的错误场景。

​
5.4 RTC 数据流业务回调

- (void)onVoiceRTCReceiveStreamMessage:(NSString *_Nullable)text
                              fromRole:(BRAIVoiceRTCStreamMessageRole)fromRole
                                   raw:(NSString *_Nullable)raw;
  • 触发时机：收到 RTC 通道传输的业务数据流时触发。
  • 参数说明：
    • text：从数据流 JSON 的 text 字段解析出的字符串，经 UTF-8 编码校验，无该字段或非字符串时为空字符串
    • fromRole：消息发送方角色，枚举值：User（用户）、Robot（机器人）、Unknown（未知）
    • raw：整条数据流 JSON 的 UTF-8 原始文本，可用于自定义业务解析

​
5.5 远端用户上线回调

- (void)onVoiceRTCRemoteUserDidJoinChannelWithUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;
  • 触发时机：远端用户（智能体机器人）成功加入当前 RTC 频道时触发。
  • 参数说明：
    • uid：远端用户的 RTC 频道唯一标识
    • elapsed：从本端加入频道到远端用户加入的时间间隔，单位为毫秒

​
5.6 远端用户下线回调

- (void)onVoiceRTCRemoteUserDidLeaveChannelWithUid:(NSUInteger)uid offlineReason:(NSInteger)offlineReason;
  • 触发时机：远端用户离开频道、主动下线或异常掉线时触发。
  • 参数说明：
    • uid：远端用户的 RTC 频道唯一标识
    • offlineReason：下线原因枚举：
      • 0：对方主动离开频道 / 正常挂断
      • 1：超时掉线（一段时间内未收到该用户数据包）
      • 2：对方将客户端角色由主播切换为观众（直播场景）
SDK 自动行为：收到本回调后，SDK 将自动启动 30 秒重连等待；若 30 秒内未收到远端用户重新上线的回调，将主动断开连接并通过 onVoiceRTCRuntimeError: 回调错误（错误码：3019）。

​
六、错误码说明

错误码详细描述
3001参数校验错误（入参为空、格式非法或缺失必要字段）
3002当前设备无可用网络连接
3003SDK 内部网络请求异常（网络中断或服务端返回非 2xx 状态码）
3004应用未获取麦克风权限
3005不支持的渠道或运行平台
3006语音引擎初始化失败
3007本端加入 RTC 频道异常
3008本端离开 RTC 频道异常
3009调用打断方法时，语音会话尚未建立
3010业务指令序列化失败
3011发送指令或业务数据流失败
3012语音引擎未初始化时调用功能方法
3013麦克风开关状态设置失败
3014底层未知系统异常
3015发起语音会话过程中底层连接中断
3016底层接收 RTC 数据流异常
3017创建业务数据流通道失败
3018本端进房后，远端用户上线超时
3019远端用户下线且重连超时
3020业务数据流 JSON 解析失败
3021调用流程互斥（例如重复发起未完成的启动请求）