本文将介绍如何快速接入 TUICallKit 组件。您可以在 10 分钟内完成以下关键步骤,最终获得一个功能完备的音视频通话界面。

准备工作
环境要求
Android 版本要求:Android 5.0(SDK API Level 21)及以上版本。
Gradle 版本要求:Gradle 4.2.1 及以上的版本。
设备需满足:Android 5.0 及以上的手机设备。
开通服务
快速接入
步骤1:导入组件
在 GitHub 中克隆或下载代码,然后将
TUIKit_Android 目录下的 atomic_x 和 call 目录下的 tuicallkit-kt 子目录复制到您当前工程的 app 同级目录中,如下图所示。
步骤2:工程配置
1. 在工程根目录下找到
settings.gradle.kts(或 settings.gradle )文件,增加如下代码,导入tuicallkit-kt、atomic_x 组件到项目中。include(":tuicallkit-kt")include(":atomic_x")
include ':tuicallkit-kt'include ':atomic_x'
2. 在 app 目录下找到
build.gradle.kts(或build.gradle) 文件,在dependencies 中增加如下代码,声明当前 app 对组件的依赖。dependencies {api(project(":tuicallkit-kt"))}
dependencies {api project(':tuicallkit-kt')}
说明:
TUICallKit 工程内部已经默认依赖:
TRTC SDK、IM SDK、tuicallengine 以及公共库 tuicore,不需要开发者单独配置。如需进行版本升级,则修改tuicallkit-kt/build.gradle文件中的版本号即可。3. 由于 SDK 内部使用了 Java 反射特性,需要将部分类加入不混淆名单。请在 app 目录下的
proguard-rules.pro 文件末尾添加如下代码。添加完后,点击右上角的 Sync Now,同步代码。-keep class com.tencent.** { *; }
4. 在 app 目录下找到
AndroidManifest.xml 文件,在 application 节点中添加 tools:replace="android:allowBackup",覆盖组件内的设置,使用自己的设置。// app/src/main/AndroidManifest.xml<applicationandroid:name=".BaseApplication"android:allowBackup="false"android:icon="@drawable/app_ic_launcher"android:label="@string/app_name"android:largeHeap="true"android:theme="@style/AppTheme"tools:replace="android:allowBackup">
说明:
如果您集成 tuicallkit-kt 后报如下错误:

原因是 AGP 8.0+ 要求 Gradle 运行时使用 Java 17 或更高版本。您可以在 Android Studio 中点击 Tools -> SDK Manager -> Build, Execution,Deployment -> Build Tools -> Gradle 配置 Gradle JDK 版本为 17 解决该问题

步骤3:登录
在您的项目中添加如下代码,调用
login 方法实现 TUI 组件的登录。这一步骤至关重要,只有在成功登录之后,您才能正常使用 TUICallKit 提供的各项功能。login
import com.tencent.qcloud.tuicore.TUILoginimport com.tencent.qcloud.tuicore.interfaces.TUICallbackimport com.tencent.qcloud.tuikit.tuicallkit.debug.GenerateTestUserSigclass MainActivity : ComponentActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)val userId = "denny" // 请替换为您的UserIdval sdkAppId = 0 // 请替换为在控制台得到的SDKAppIDval secretKey = "****" // 请替换为在控制台得到的SecretKeyval userSig = GenerateTestUserSig.genTestUserSig(userId, sdkAppId, secretKey)TUILogin.login(this, sdkAppId, userId, userSig, object : TUICallback() {override fun onSuccess() {}override fun onError(errorCode: Int, errorMessage: String) {}})}}
import com.tencent.qcloud.tuicore.TUILogin;import com.tencent.qcloud.tuicore.interfaces.TUICallback;import com.tencent.qcloud.tuikit.tuicallkit.debug.GenerateTestUserSig;public class MainActivity extends AppCompatActivity {@Overridepublic void onCreate(Bundle savedInstanceState) {super.onCreate(savedInstanceState);String userId = "denny"; // 请替换为您的UserIdint sdkAppId = 0; // 请替换为第一步在控制台得到的SDKAppIDString secretKey = "****"; // 请替换为第一步在控制台得到的SecretKeyString userSig = GenerateTestUserSig.genTestUserSig(userId, sdkAppId, secretKey);TUILogin.login(this, sdkAppId, userId, userSig, new TUICallback() {@Overridepublic void onSuccess() {}@Overridepublic void onError(int errorCode, String errorMessage) {}});}}
参数 | 类型 | 说明 |
userId | String | 只允许包含大小写英文字母(a-z A-Z)、数字(0-9)及下划线和连词符。 |
sdkAppId | int | |
secretKey | String | |
userSig | String | 一种安全保护签名,用于对用户进行登录鉴权认证,确认用户是否真实,阻止恶意攻击者盗用您的云服务使用权。 |
说明:
开发环境:如果您在本地开发调试阶段,可以采用本地 GenerateTestUserSig.genTestUserSig 函数生成 userSig。该方法中 secretKey 很容易被反编译逆向破解,一旦您的密钥泄露,攻击者就可以盗用您的腾讯云流量。
生产环境:如果您的项目要发布上线,请采用 服务端生成 UserSig 的方式。
步骤4:设置昵称和头像[可选]
首次登录的用户没有头像和昵称信息,您可以通过
setSelfInfo 接口设置头像和昵称:setSelfInfo
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKitval name = "mike" // 目标用户的昵称。val avatar = "https:/****/user_avatar.png" // 目标用户的头像。TUICallKit.createInstance(applicationContext).setSelfInfo(name, avatar,object : CompletionHandler {override fun onSuccess() {// 设置成功}override fun onFailure(code: Int, desc: String) {// 设置失败}})
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKit;String name = "mike"; // 目标用户的昵称。String avatar = "https:/****/user_avatar.png"; // 目标用户的头像。TUICallKit.createInstance(applicationContext).setSelfInfo(name, avatar,new CompletionHandler() {@Overridepublic void onSuccess() {// 设置成功}@Overridepublic void onFailure(int code, String desc) {// 设置失败}});
参数 | 类型 | 说明 |
nickname | String | 目标用户的昵称。 |
avatar | String | 目标用户的头像。 |
completion | CompletionHandler | 异步操作的结果回调。 |
步骤5:发起通话
拨打方可以通过调用
calls 函数,并指定通话类型和被叫方的 userID,来发起语音或视频通话。calls 接口同时支持一对一通话和多人通话。当 userIDList 中包含一个 userID 时,为一对一通话;当 userIDList 包含多个 userID 时,则为多人通话。calls
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKitimport io.trtc.tuikit.atomicxcore.api.call.CallMediaTypeimport io.trtc.tuikit.atomicxcore.api.call.CallParamsval userIdList = mutableListOf<String>()userIdList.add("mike")val mediaType = CallMediaType.Audioval callParams = CallParams()TUICallKit.createInstance(context).calls(userIdList, mediaType, params, object : CompletionHandler {override fun onFailure(code: Int, desc: String) {// 失败回调}override fun onSuccess() {// 成功回调}})
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKit;import io.trtc.tuikit.atomicxcore.api.call.CallMediaType;import io.trtc.tuikit.atomicxcore.api.call.CallParams;List<String> userIdList = new ArrayList<>();userIdList.add("mike");CallMediaType mediaType = CallMediaType.Audio;CallParams params = new CallParams();TUICallKit.createInstance(this).calls(userIdList, mediaType, params, new CompletionHandler() {@Overridepublic void onFailure(int code, String desc) {// 失败回调}@Overridepublic void onSuccess() {// 成功回调}});
参数 | 类型 | 说明 |
userIdList | List<String> | 目标用户的 userId 列表。 |
mediaType | 通话的媒体类型,例如视频通话、语音通话。 Audio : 语音通话。 Video : 视频通话。 | |
params | 通话扩展参数,例如房间号、通话邀请超时时间等。 roomId : 此次通话的房间 ID。 timeout : 发起通话等待的最长时间,超过该时间通话结束。 userData : 发起通话时自定义扩展字段。 chatGroupId : 与 chat 结合使用,Chat 群组的群 ID 。 | |
completion | CompletionHandler | 异步操作的结果回调。 |
步骤6:接听通话
接听端完成登录后,拨打端发起通话,接收端就可以收到通话邀请,同时伴随铃声和振动。
更多功能
开启悬浮窗功能
您可以通过调用
enableFloatWindow 开启/关闭悬浮窗功能,在初始化 TUICallKit 组件时启用该功能,默认状态为关闭(false)。可通过点击通话界面左上角的悬浮窗按钮,将通话界面缩小为悬浮窗形式。
enableFloatWindow
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKitTUICallKit.createInstance(this).enableFloatWindow(true)
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKit;TUICallKit.createInstance(this).enableFloatWindow(true);
详情:默认为 false,通话界面左上角的悬浮窗按钮隐藏,设置为 true 后显示。
开启来电横幅
您可以通过调用
enableIncomingBanner 开启/关闭来电横幅显示,该功能默认为关闭状态(false)。当被叫端收到来电时,默认展示全屏通话等待界面。启用此功能后,将首先显示一个横幅通知,然后根据需要切换到全屏通话界面。请注意,显示来电横幅需要授予悬浮窗权限,具体的显示策略将根据权限设置及应用当前是否在前台或后台运行来决定,具体策略可参考:被叫端来电显示策略。
enbaleIncomingBanner
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKitTUICallKit.createInstance(context).enableIncomingBanner(true)
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKit;TUICallKit.createInstance(context).enableIncomingBanner(true);
详情:默认为 false,被叫端收到邀请后默认弹出全屏通话等待界面。开启后先展示一个横幅,然后根据需要拉起全屏通话界面。
实现多人通话
主叫方使用
calls 方法发起通话时,若被叫用户列表超过一人,则自动视为群组通话。其他成员可通过 join 方法加入该多人通话。发起多人通话:使用
calls 方法发起通话时,若被叫用户列表(userIdList)超过一人,则自动视为群组通话。calls
import com.tencent.cloud.tuikit.engine.call.TUICallDefineimport com.tencent.qcloud.tuikit.tuicallkit.TUICallKitimport io.trtc.tuikit.atomicxcore.api.call.CallMediaTypeimport io.trtc.tuikit.atomicxcore.api.call.CallParamsval userIdList = mutableListOf<String>()userIdList.add("mike")userIdList.add("tate")val mediaType = CallMediaType.Audioval params = CallParams()TUICallKit.createInstance(context).calls(userIdList, mediaType, params, object : CompletionHandler {override fun onFailure(code: Int, desc: String) {// 失败回调}override fun onSuccess() {// 成功回调}})
import com.tencent.cloud.tuikit.engine.call.TUICallDefine;import com.tencent.qcloud.tuikit.tuicallkit.TUICallKit;import io.trtc.tuikit.atomicxcore.api.call.CallMediaType;import io.trtc.tuikit.atomicxcore.api.call.CallParams;List<String> userIdList = new ArrayList<>();userIdList.add("mike");userIdList.add("tate");CallMediaType mediaType = CallMediaType.Audio;CallParams params = new CallParams();TUICallKit.createInstance(context).calls(userIdList, mediaType, params, new CompletionHandler() {@Overridepublic void onFailure(int code, String desc) {// 失败回调}@Overridepublic void onSuccess() {// 成功回调}});
参数 | 类型 | 说明 |
userIdList | List<String> | 目标用户的 userId 列表。 |
mediaType | 通话的媒体类型,例如视频通话、语音通话。 Audio : 语音通话。 Video : 视频通话。 | |
params | 通话扩展参数,例如房间号、通话邀请超时时间等。 roomId : 此次通话的房间 ID。 timeout : 发起通话等待的最长时间,超过该时间通话结束。 userData : 发起通话时自定义扩展字段。 chatGroupId : 与 chat 结合使用,Chat 群组的群 ID 。 | |
completion | CompletionHandler | 异步操作的结果回调。 |
加入多人通话:可使用
join 方法加入指定的群组通话。join
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKitval callId = "123456" // 此次通话的 IDTUICallKit.createInstance(this).join(callId, object : CompletionHandler {override fun onFailure(code: Int, desc: String) {// 失败回调}override fun onSuccess() {// 成功回调}})
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKit;String callId = "123456"; // 此次通话的 IDTUICallKit.createInstance(this).join(callId, new CompletionHandler() {@Overridepublic void onFailure(int code, String desc) {// 失败回调}@Overridepublic void onSuccess() {// 成功回调}});
参数 | 类型 | 说明 |
callId | String | 此次通话的唯一标识。 |
completion | CompletionHandler | 异步操作的结果回调。 |
设置语言
支持的语言:目前支持简体中文、繁体中文、英文、日文和阿拉伯语。
切换语言:TUICallKit 默认语言与手机系统保持一致 。如果需要切换语言,可以使用
TUIThemeManager.getInstance().changeLanguage 方法设置语言,以设置语言为英文的示例代码如下。 changeLanguage
import com.tencent.qcloud.tuicore.TUIThemeManager;public class MainActivity extends BaseActivity {@Overridepublic void onCreate(Bundle savedInstanceState) {super.onCreate(savedInstanceState)val language = TUIThemeManager.LANGUAGE_ZH_CN // 设置的语言TUIThemeManager.getInstance().changeLanguage(applicationContext, language)}}
import com.tencent.qcloud.tuicore.TUIThemeManager;public class MainActivity extends BaseActivity {@Overridepublic void onCreate(Bundle savedInstanceState) {super.onCreate(savedInstanceState);String language = TUIThemeManager.LANGUAGE_EN; // 设置的语言TUIThemeManager.getInstance().changeLanguage(getApplicationContext(), language);}}
参数 | 类型 | 说明 |
language | String | 设置的语言: TUIThemeManager.LANGUAGE_EN:英文。 TUIThemeManager.LANGUAGE_AR:阿拉伯语。 TUIThemeManager.LANGUAGE_ZH_HK:中文繁体。 TUIThemeManager.LANGUAGE_ZH_CN:中文简体。 |
说明:
设置铃声
您可通过以下方式设置默认铃声、来电静音模式、离线推送铃声:
设置默认铃声(方式2):通过 setCallingBell 接口设置被叫端收到的来电铃声。
setCallingBell
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKitval filePath = "***/callingBell.mp3"TUICallKit.createInstance(context).setCallingBell(filePath)
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKit;String filePath = "***/callingBell.mp3";TUICallKit.createInstance(context).setCallingBell(filePath);
详情:这里仅限传入本地文件地址,需要确保该文件目录是应用可以访问的。铃声设置后与设备绑定,更换用户,铃声依旧会生效。如需恢复默认铃声,filePath传空即可。
参数 | 类型 | 说明 |
filePath | String | 铃声文件的路径。 |
来电静音模式:您可以通过 enableMuteMode 设置静音模式。
enableMuteMode
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKitTUICallKit.createInstance(context).enableMuteMode(true)
import com.tencent.qcloud.tuikit.tuicallkit.TUICallKit;TUICallKit.createInstance(context).enableMuteMode(true);
详情:开启后,收到通话请求,不会播放来电铃声。
自定义离线推送铃声:离线推送默认铃声是由系统决定的,可以在 手机设置 中,进入应用详情,查看或更改应用的通知铃声。
自定义您的 UI
替换图标按钮
常用图标文件名列表
图标 | 文件名称 | 说明 |
![]() | callview_ic_dialing.png | 接听来电图标 |
![]() | callview_ic_hangup.png | 挂断通话图标 |
![]() | callview_ic_mic_unmute.png | 关闭麦克风图标 |
![]() | callview_ic_handsfree_disable.png | 关闭扬声器图标 |
![]() | callview_ic_camera_disable.png | 关闭摄像头图标 |
![]() | callview_ic_add_user_black.png | 通话过程中邀请用户图标 |





