概述

双向语音API 提供了完整的聊天室功能,通过在应用中接入双向语音API,能够实现多人实时的双向语音通话功能。本文档旨在说明双向语音API基本接口的使用以及注意事项,具体的接口定义请参考接口头文件。

双向语音API 适用于iOS 6.0 及以上操作系统的设备。

接入双向语音API

1. 申请APP KEY

在双向语音管理后台创建一款应用,您将获得与您应用相关联的唯一标识。

2. 向工程导入双向语音API

下载双向语音API 后解压至本地目录,将其中的.h 和lib.a 导入到您的应用工程中。在您的工程里,选择File→Add Files to "Your Project"→选择双向语音API 包中的所有.h 文件和.a 文件并勾选Copy items into destination group’s folder(if needed)并确保所有用到API的targets 都处于选中状态。

3. 添加依赖框架(Frameworks)

在您的工程里,选择target → Build Phases → Link Binary With Libraries, 点击+号,选择以下框架:

框架名称作用
MobileCoreServices.framework使用网络
SystemConfiguration.framework获取网络状况
AudioToolbox.framework录制和播放语音
CFNetwork.framework允许程序联网和发送语音数据的权限
libz.1.2.5.dylib进行数据压缩

4. 创建双向语音API实例并初始化环境

使用双向语音API 首先必须调用API 的初始化函数,这样才能正确使用API 的功能:

// 添加头文件
#import "VoiChannelAPI.h"

// 初始化实例
VoiChannelAPI *api = [VoiChannelAPI defaultAPI];

// 初始化appkey
[api setAppKey:@"您在双向语音管理后台申请的APP KEY "];

如果在同一进程中多次调用initWithAppKey,传入参数不同,会以首次调用为准。建议初始化放在Application的初始化函数如(viewDidLoad)中调用,避免以下不必要的错误。

注意1:初始化是API 开始工作的关键,不进行初始化就对其它接口进行调用,请开发者一定注意。

功能说明

1. 注册或取消回调

双向语音API的回调协议为VoiChannelAPIDelegate。开发者应在需要回调消息的模块中继承回调协议VoiChannelAPIDelegate,并调用添加回调通知函数。

// 继承协议
@interface YourViewController : UIViewController
<VoiChannelAPIDelegate>
YourViewController *apiView = [[YourViewController alloc]init];

// 添加监听
[api addListener: apiView];

在不需要监听回调事件的时候,移除回调:

[api removeListener: apiView];

注意1:务必在不使用回调后删除回调,不删除会导致回调过多,并且多次调用而出现一些不必要的问题。

2. 双向语音API异常处理

双向语音API 许多请求都是通过回调通知上层,当用户操作失败,或出现网络异常时,本地将会收到一个onError的回调,其参数errorCode的值对应了不同的错误,详细的值请参见头文件中的ErrorType 枚举说明。

3. 加入和退出频道

加入频道:

//channelID 为频道的ID 号,注:频道ID 可以由开发者应用自身业务服务器通过双向语音后台接口创建频道获取。
//频道密码,如无密码传nil
[api joinChannel:channelID password:nil];

注:在加入频道之前,需要先设置用户的登录信息(包括用户 ID,用户昵称):

LoginInfo *info = [[LoginInfo alloc] initWithUserId: @"用户 ID" nickname: @"用户昵称"];
[api setLoginInfo:info];

对应回调有:

onJoinChannel:登陆频道成功
onGetChannelMember:频道所有成员(自己除外)的用户ID(String)
notifyChannelMemberTypes:频道所有成员的类型信息(MemberType)
notifyChannelTalkMode:频道的当前发言模式(TalkMode)

频道其他成员回调有:

onGetChannelMember:刚进频道成员的用户ID(String)
notifyChannelMemberTypes:频道所有成员的类型信息(MemberType)

退出当前频道:

[api exitChannel];

对应回调为:

onExitChannel:退出频道是否成功

频道其他成员回调为:

onRemoveChannelMember:收到其他成员刚退出的通知

注意1:退出频道将会取消说话模式,恢复麦克风和扬声器(只针对被别人禁用的)。

4. 获取用户昵称

得到用户的ID 后,可以通过该ID 去获取用户昵称,支持批量获取:

[api requestUserNickname:@[ @"用户ID1", @"用户ID2"]];

对应的回调为: onGetUserNickname:参数为用户昵称的key - value 对,key 值为用户id,value值为用户昵称。

5. 开始和停止说话

开始说话:

[api startTalking];

对应回调为:

onStartTalking:收到自己在说话的通知

频道其他成员回调为:

onStartTalking:收到频道中其他成员在说话的通知

停止说话:

[api stopTalking];

对应回调为:

onStopTalking:收到自己暂停说话的通知

频道其他成员回调为:

onStopTalking:收到频道中其他成员暂停说话的通知

6. 统计语音发送数据

在发送语音过程中,如果需要获取当前已发送的语音数据的流量,可通过接口getCurrentVoiceTrafficSend得到,单位为字节数byte。该统计在每次重新调用startTalking 之后会重置计数。

7. 禁用和恢复本地的麦克风和扬声器

禁用本地的麦克风和扬声器:

[api mute];

对应回调有:

onMuteStateChanged:收到自己静音状态的通知(布尔值为true)

恢复本地的麦克风和扬声器:

[api restore];

对应回调有:

onMuteStateChanged:收到自己禁用的通知(布尔值为false)

8. 禁言和取消禁言

禁言频道成员:

[api silence:userID];

对应回调有:

onMuteStateChanged:收到用户被禁用的通知(布尔值为true)

频道其他成员回调为:

onSilencedStateChanged:收到用户被禁用的通知(布尔值为true)

恢复其他成员的麦克风和扬声器:

[api unsilence:userID];

对应回调有:

onSilencedStateChanged:收到用户被禁用的通知(布尔值为true)

频道其他成员回调为:

onSilencedStateChanged:收到用户被禁用的通知(布尔值为false)

注意1:普通用户没有此操作权限。

9. 提升和取消管理员

提升管理员和取消管理员的回调相同:

[api elevate:userID];//提升管理员
[api demote:userID]; //取消管理员

对应回调有:

notifyChannelMemberTypes:频道所有成员的类型信息(MemberType)
notifyChannelTalkMode:频道的当前发言模式(TalkMode)

频道其他成员回调有:

notifyChannelTalkMode:频道的当前发言模式(TalkMode)
notifyChannelMemberTypes:频道所有成员的类型信息(MemberType)

注意1:普通用户没有此操作权限。

10. 设置频道发言模式

发言模式分为管理员发言模式和自由发言模式

[api setChannelTalkMode:Freedom];//自由发言模式
[api setChannelTalkMode:AdministratorOnly];//管理员发言模式

对应回调有:

notifyChannelMemberTypes:频道所有成员的类型信息(MemberType)
notifyChannelTalkMode:频道的当前发言模式(TalkMode)

频道其他成员回调有:

notifyChannelTalkMode:频道的当前发言模式(TalkMode)
notifyChannelMemberTypes:频道所有成员的类型信息(MemberType)

注意1:如果设置的是管理员发言模式,则所有普通用户将会停止发言,其状态将会通知给所有频道成员。 注意2:普通用户没有此操作权限。

11. 退出语音服务器请调用以下代码

[api exit];

对应回调为 onExit 方法 注意:退出语音服务器,将恢复 app 最初状态。

Q&A

1. 如何确定我的集成是正确的?

解答:集成后请务必进行必要的真机测试,使用双向语音API能够登录成功,发送登陆频道消息。如果程序能正常接收发送消息则表示集成成功。

返回顶部