# 实现语聊房 (/zh-CN/solutions/chatroom/sdk/build/quick-integration/android)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## 示例项目 [#示例项目]
本文介绍如何实现语聊房,包含登录系统、初始化引擎、创建房间、麦位管理、退出房间。声网在 `agora-ent-scenarios` 仓库中提供实现语聊房的源代码供你参考。
## 业务流程 [#业务流程]
本节展示语聊房中常见的业务流程。
### 进出房间 [#进出房间]
下图展示创建、进入、退出房间的流程。
### 房主邀请听众上麦 [#房主邀请听众上麦]
下图展示房主邀请听众上麦的流程。在这个流程中,房主发起上麦邀请。如果听众接受邀请,房主会收到通知并修改麦位信息,让听众上麦。听众随后发布自己的音频流。
### 听众申请上麦 [#听众申请上麦]
下图展示听众向房主申请上麦的流程。在这个流程中,听众主动发起上麦申请,如果房主接受申请,房主修改麦位信息以让听众上麦。听众收到上麦消息后,发布自己的音频流。
## 准备开发环境 [#准备开发环境]
### 前提条件 [#前提条件]
开始前,请确保你的开发环境满足如下要求:
- [Android Studio](https://developer.android.com/studio/) 3.5 及以上。
- Android 手机,版本 Android 5.0(API Level 21)及以上。
- 可以访问互联网的计算机。确保你的网络环境没有部署防火墙,否则无法正常使用声网服务。
- 参考[开通语聊房 SDK 相关服务](/zh-CN/solutions/chatroom/sdk/build/enable-service)创建声网开发者账号和声网项目,并获取项目的 App ID 和临时 Token,以及登录即时通讯系统所需的用户名 (ID) 和 Token。
### 集成 SDK [#集成-sdk]
声动语聊用到声网实时互动 (RTC) SDK 和即时通讯 (IM) SDK。本节介绍如何在 Android Studio 创建项目并集成这两个 SDK:
1. 如需创建新项目,在 **Android Studio** 里,依次选择 **Phone and Tablet > Empty Activity**,创建 [Android 项目](https://developer.android.com/studio/projects/create-project)。
:::info[信息]
创建项目后,**Android Studio** 会自动开始同步 Gradle,稍等片刻至同步成功后再进行下一步操作。
:::
2. 使用 Maven Central 将声网 RTC SDK 和 IM SDK 集成到你的项目中。
1. 在 `/Gradle Scripts/build.gradle(Project: )` 文件中添加如下代码,添加 Maven Central 依赖:
```groovy
buildscript {
repositories {
...
mavenCentral()
}
...
}
allprojects {
repositories {
...
mavenCentral()
}
}
```
:::info[信息]
如果你的 Android 项目设置了 [dependencyResolutionManagement](https://docs.gradle.org/current/userguide/centralizing_repositories.html),添加 Maven Central 依赖的方式可能存在差异。
:::
2. 在 `/Gradle Scripts/build.gradle(Module: .app)` 文件中添加如下代码,将声网 RTC SDK 和 IM SDK 集成到你的 Android 项目中:
```groovy
...
dependencies {
...
// x.y.z,请填写具体的 SDK 版本号,如:4.0.0 或 4.1.0-1
// 通过实时互动产品发版说明获取最新版本号
implementation 'io.agora.rtc:full-sdk:x.y.z'
// 指定 IM SDK 1.1.0 版
implementation 'io.agora.rtc:chat-sdk:1.1.0'
}
```
3. 添加网络及设备权限。
在 `/app/Manifests/AndroidManifest.xml` 文件中,在 `` 后面添加如下权限:
```xml
```
4. 在 `/Gradle Scripts/proguard-rules.pro` 文件中添加如下行,以防止声网 SDK 的代码被混淆:
```kotlin
-keep class io.agora.**{*;}
-dontwarn javax.**
-dontwarn com.google.devtools.build.android.**
```
## 实现语聊房 [#实现语聊房]
你需要声网 RTC SDK、IM SDK 和云服务 (Service) 共同搭建语聊房场景。其中:
- 实时互动 RTC SDK 承担实时音频的业务。
- 即时通讯 IM SDK 实现房间内的信令通信。
- 云服务 (Service) 实现了房间列表的存储和房间生命周期的管理。
本节会详细介绍如何调用声网云服务(`voiceServiceProtocol`)、IM SDK 和 RTC SDK 的 API 完成登录即时通讯系统、获取房间列表、创建房间、进入房间、加入 RTC 房间、离开 RTC 房间等关键逻辑。完整的调用时序可以参考 [API 时序图](#api-时序图)。
:::warning[注意]
声网云服务为内部自研服务,暂不对外提供。你可以调用声网云服务的 API 用于测试,但是对于正式环境,声网建议你参考文档自行实现相似的一套服务。如需协助,请[联系技术支持](https://ticket.shengwang.cn/)。
:::
### 1. 获取房间列表 [#1-获取房间列表]
调用声网云服务中 `voiceServiceProtocol` 类的 `fetchRoomList` 方法获取房间列表。获取到房间列表后刷新 UI 并将房间列表展示在界面上。
```kotlin
voiceServiceProtocol.fetchRoomList(page, completion = { error, result ->
...
})
```
### 2. 登录即时通讯系统 [#2-登录即时通讯系统]
参考如下步骤登录即时通讯 (IM) 系统:
1. 根据[前提条件](#前提条件)开启声网即时通讯服务,并获取登录即时通讯系统所需的用户名 (ID) 和 Token。
2. 调用声网即时通讯 (IM) SDK 中 `ChatClient` 类的 [`loginWithToken`](https://docs-preprod.agora.io/cn/agora-chat/API%20Reference/im_java/v1.1.0/classio_1_1agora_1_1chat_1_1_chat_client.html#ac2b19ffdcd879b5f239baacbaa09423b) 方法并传入即时通讯服务的用户名和 Token 以登录即时通讯系统。
```kotlin
public void login(String uid,String token,CallBack callBack){
ChatClient.getInstance().loginWithToken(uid, token, new CallBack() {
@Override
public void onSuccess() {
ThreadManager.getInstance().runOnMainThread(new Runnable() {
@Override
public void run() {
callBack.onSuccess();
}
});
LogTools.d("ChatroomConfigManager","Login success");
}
@Override
public void onError(int code, String msg) {
ThreadManager.getInstance().runOnMainThread(new Runnable() {
@Override
public void run() {
callBack.onError(code,msg);
}
});
LogTools.e("ChatroomConfigManager", "Login onError code:" + code + " desc: " + msg);
}
});
}
```
### 3. 初始化 `RtcEngine` [#3-初始化-rtcengine]
参考如下步骤初始化 `RtcEngine`:
1. 根据[开通语聊房 SDK 相关服务](/zh-CN/solutions/chatroom/sdk/build/enable-service)在声网控制台创建声网项目后,复制界面的 App ID。
2. 调用声网 RTC SDK 中的 [`create`](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 方法创建并初始化 `RtcEngine`。
```kotlin
// 初始化配置
val config = RtcEngineConfig()
// 设置 App ID
config.mAppId = "YourAppId"
// 创建 RtcEngine 实例
val rtcEngine = RtcEngineEx.create(config) as RtcEngineEx
```
### 4. 创建并进入房间 [#4-创建并进入房间]
参考如下步骤创建并进入房间:
1. 调用 `voiceServiceProtocol` 对象中的 `createRoom` 方法创建一个房间。
```kotlin
val voiceCreateRoomModel = VoiceCreateRoomModel(
roomName = roomName,
soundEffect = soundEffect,
isPrivate = !TextUtils.isEmpty(password),
password = password ?: "",
roomType = roomType
)
voiceServiceProtocol.createRoom(voiceCreateRoomModel, completion = { error, result ->
when (error) {
VoiceServiceProtocol.ERR_OK -> {
callBack.onSuccess(createLiveData(result))
}
VoiceServiceProtocol.ERR_ROOM_NAME_INCORRECT -> {
callBack.onError(error, "")
}
else -> {
callBack.onError(error, "")
}
}
})
```
2. 调用 `voiceServiceProtocol` 对象的 `joinRoom` 方法进入房间。
```kotlin
voiceServiceProtocol.joinRoom(roomId, completion = { error, result ->
when (error) {
VoiceServiceProtocol.ERR_OK -> {
callBack.onSuccess(createLiveData(result))
}
VoiceServiceProtocol.ERR_ROOM_UNAVAILABLE -> {
callBack.onError(error, "room is not existent")
}
else -> {
callBack.onError(error, "")
}
}
})
```
3. 语聊房里需要有消息聊天和语音聊天,因此你还需进行如下操作:
- 调用声网 IM SDK 中 `joinChatRoom` 实现房间内的消息互动。方法中的参数含义和取值请参考 [`joinChatRoom`](https://docs-preprod.agora.io/cn/agora-chat/API%20Reference/im_java/v1.1.0/classio_1_1agora_1_1chat_1_1_chat_room_manager.html#a895dbd6d0217ba08bcf2dbb6cf441591)。
```kotlin
// 实现房间内的消息互动
public void joinRoom(String chatroomId, ValueCallBack callBack){
ChatClient.getInstance().chatroomManager()
.joinChatRoom(chatroomId, new ValueCallBack() {
@Override
public void onSuccess(ChatRoom value) {
ThreadManager.getInstance().runOnMainThreadDelay(new Runnable() {
@Override
public void run() {
callBack.onSuccess(value);
}
},200);
}
@Override
public void onError(int error, String errorMsg) {
ThreadManager.getInstance().runOnMainThread(new Runnable() {
@Override
public void run() {
callBack.onError(error,errorMsg);
}
});
}
});
}
```
- 调用声网 RTC SDK 中 `RtcEngine` 类的 `joinChannel` 加入 RTC 频道以实现房间内的实时音频通话。方法中的参数含义和支持取值请参考 [`joinChannel`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_joinchannel2)。在这一步里需要填写声网 RTC Token。你可以使用[开通语聊房 SDK 相关服务](/zh-CN/solutions/chatroom/sdk/build/enable-service)中获取的临时 Token,也可以参考[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)获取正式用途的声网 RTC Token。临时 Token 的有效期为 24 小时,建议你仅在测试用途下使用。
你还可以调用 [`setChannelProfile`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_setchannelprofile)、[`setAudioProfile`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_setaudioprofile2)、[`setAudioScenario`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_setaudioscenario)、[`setParameters`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_setparameters) 为不同业务场景(语聊社交、KTV、游戏陪玩、专业音频直播场景)配置语聊房的推荐音效参数。
```kotlin
// 实现房间内的语音互动
rtcEngine?.apply {
when (soundEffect) {
// 在线 K 歌房和泛娱乐社交场景下推荐设置
ConfigConstants.SoundSelection.Social_Chat,
ConfigConstants.SoundSelection.Karaoke -> {
// 设置频道属性为直播
setChannelProfile(Constants.CHANNEL_PROFILE_LIVE_BROADCASTING)
// 设置 48 kHz 采样率,音乐编码,单声道,编码码率最大值为 96 Kbps
setAudioProfile(Constants.AUDIO_PROFILE_MUSIC_HIGH_QUALITY)
// 设置为高音质场景
setAudioScenario(Constants.AUDIO_SCENARIO_GAME_STREAMING)
}
// 1 对 1 游戏陪玩通话场景下推荐
ConfigConstants.SoundSelection.Gaming_Buddy -> {
// 设置频道属性为通信
setChannelProfile(Constants.CHANNEL_PROFILE_COMMUNICATION)
}
else -> {
// 专业音频直播场景下推荐设置
// 设置频道属性为直播
setChannelProfile(Constants.CHANNEL_PROFILE_LIVE_BROADCASTING)
// 指定 48 kHz 采样率,音乐编码,双声道,编码码率最大值为 128 Kbps
setAudioProfile(Constants.AUDIO_PROFILE_MUSIC_HIGH_QUALITY)
// 设置为高音质场景
setAudioScenario(Constants.AUDIO_SCENARIO_GAME_STREAMING)
// 设置私有参数以获得好的实时音频互动体验
setParameters("{\"che.audio.custom_payload_type\":73}")
setParameters("{\"che.audio.custom_bitrate\":128000}")
setParameters("{\"che.audio.input_channels\":2}")
}
}
}
// 加入 RTC 频道
// 此处的 Token 为声网 RTC Token
val status = rtcEngine?.joinChannel(VoiceBuddyFactory.get().getVoiceBuddy().rtcToken(), channelId, "", rtcUid)
```
### 5. 麦位管理 [#5-麦位管理]
具体步骤详见[麦位管理](/zh-CN/solutions/chatroom/sdk/build/mic-seat-management)。
### 6. 退出房间 [#6-退出房间]
参考如下步骤退出并销毁语聊房。
1. 调用 `voiceServiceProtocol` 对象的 `leaveRoom` 方法离开房间。
```kotlin
voiceServiceProtocol.leaveRoom(roomId, isRoomOwnerLeave, completion = { error, result ->
...
})
```
2. 调用 `RtcEngine` 类的 [`leaveChannel`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_leavechannel) 方法离开 RTC 频道。
```kotlin
rtcEngine?.leaveChannel()
```
3. 调用 [`leaveChatRoom`](https://docs-preprod.agora.io/cn/agora-chat/API%20Reference/im_java/v1.1.0/classio_1_1agora_1_1chat_1_1_chat_room_manager.html#a4f2c430782206971480c73a49311b1437) 离开聊天室,调用 [`asyncDestroyChatRoom`](https://docs-preprod.agora.io/cn/agora-chat/API%20Reference/im_java/v1.1.0/classio_1_1agora_1_1chat_1_1_chat_room_manager.html?transId=194274c0-bee4-11ed-b167-a39cc89dc96e#a0d50d2e34d9992fc3f8ea1c82e2db1a) 销毁聊天室。调用 [`destroy`](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_release) 销毁 RTC 引擎。
```kotlin
ChatroomIMManager.getInstance().leaveChatRoom(roomKitBean.chatroomId)
ChatroomIMManager.getInstance().asyncDestroyChatRoom(roomKitBean.chatroomId, object :
CallBack {
override fun onSuccess() {}
override fun onError(code: Int, error: String?) {}
})
RtcEngineEx.destroy()
rtcEngine = null
```
### API 时序图 [#api-时序图]
如下时序图展示了如何登录即时通讯系统、获取房间列表、创建房间、进入房间、加入 RTC 频道、麦位管理、退出房间、离开 RTC 频道。