tencent cloud

实时音视频

文档实时音视频视频通话 SDK快速接入Flutter

Flutter

Download
聚焦模式
字号
最后更新时间： 2026-07-10 15:25:06
本文将介绍如何快速接入 TUICallKit 组件。您可以在 10 分钟内完成以下关键步骤，最终获得一个功能完备的音视频通话界面。


准备工作

环境要求

Flutter 3.24.0、Dart 3.5.0 及以上版本。

开通服务

在使用腾讯云提供的音视频服务前，您需要前往控制台，为应用开通音视频服务。具体步骤详细参见：开通服务。开通服务后，请记录 SDKAppID 和 SDKSecretKey，在后续的步骤（登录）中会用到。

快速接入

步骤1: 导入插件

在工程的根目录下，通过命令行执行以下命令安装 tencent_calls_uikit 插件。
flutter pub add tencent_calls_uikit

步骤2: 工程配置

原生工程配置：
Android
iOS
1. 由于 SDK 内部使用了 Java 反射机制（或特性），需要将部分 SDK 类加入不进行混淆处理的名单。
请在工程的 android/app/ 目录下找到 build.gradle.kts（或 build.gradle ）文件中配置并开启混淆规则：
build.gradle.kts
build.gradle
android {
    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android.txt"),
                "proguard-rules.pro"
            )
        }
    }
}
android {
    buildTypes {
        release {
            minifyEnabled true 
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}
在工程的 android/app 目录下创建 proguard-rules.pro 文件，并在其中添加如下代码：
-keep class com.tencent.** { *; }
2. （可选）如果您需要在应用外使用 CallKit 的悬浮窗能力，需要开启系统画中画特性。
请在 App 主工程的 AndroidManifest.xml 里设置 MainActivity 的 android:supportsPictureInPicture 为 true：
  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <activity
            android:name=".MainActivity"
            android:supportsPictureInPicture="true"
        </activity>
    </application>
</manifest>
因为 TUICallKit 需要使用音视频功能，您必须获取麦克风和摄像头的授权。
授权操作方法：在您的 iOS 工程的 Info.plist 文件中，在顶级 <dict> 目录下添加以下两项。
<key>NSCameraUsageDescription</key>
<string>CallingApp需要访问您的相机权限，开启后录制的视频才会有画面</string>
<key>NSMicrophoneUsageDescription</key>
<string>CallingApp需要访问您的麦克风权限，开启后录制的视频才会有声音</string>
注意：
由于 tencent_rtc_sdk 通过 Flutter FFI 调用接口，iOS Release 构建时 Xcode 的符号裁剪优化可能误移除 TRTC 的 C 符号，引发 `symbol not found` 错误。解决方案如下：
1. 在项目的 Build Settings 中找到 deployment postprocessing，将其设置为 Yes 。

2. 在项目的 Build Settings 中找到 strip style，将其中 Release 的值设置为 Non-Global Symbols 。

Flutter 工程配置
为了确保 TUICallKit 能够正常管理页面导航和显示多语言界面，需要在 Flutter 应用框架中进行以下配置：
在 navigatorObservers 中添加 TUICallKit.navigatorObserver，用于监听页面路由变化和管理组件生命周期。
在 localizationsDelegates 中添加相关本地化代理，确保界面文案能够根据系统语言正确显示。
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';

 ......

class XXX extends StatelessWidget {
  const XXX({super.key});

 @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorObservers: [TUICallKit.navigatorObserver],
      localizationsDelegates: const [
        // 您的 App 其他配置
        AtomicLocalizations.delegate,
      ],
    );
  }
}

步骤3: 登录

在您的项目中添加如下代码，调用 login 接口完成插件的登录。此步骤至关重要：只有成功登录后，您才能正常使用 TUICallKit 提供的各项功能。
login
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';
import 'package:tencent_calls_uikit/src/debug/generate_test_user_sig.dart';
......

final String userId    = 'xxxxx';  // 请替换为您的 UserId
final int    sdkAppId  = 0;        // 请替换为第一步在控制台得到的 SDKAppId
final String secretKey = 'xxxx';   // 请替换为第一步在控制台得到的 SecretKey

void login() async {
    String userSig  = GenerateTestUserSig.genTestSig(userId, sdkAppId, secretKey);
    CompletionHandler result = await TUICallKit.instance.login(sdkAppId, userId, userSig);
    if (result.errorCode == 0) {
      print('Login success');
    } else {
      print('Login failed: ${result.errorCode} ${result.errorMessage}');
    }
}
参数
类型
说明
userId
String
客户根据自己的业务自定义用户 ID，只允许包含大小写英文字母(a-z A-Z)、数字(0-9)及下划线和连词符。
sdkAppId
int
在 实时音视频 TRTC 控制台 创建的音视频应用的唯一标识。
secretKey
String
在 实时音视频 TRTC 控制台 创建的音视频应用的 SDKSecretKey。
userSig
String
一种安全保护签名，用于对用户进行登录鉴权认证，确认用户是否真实，阻止恶意攻击者盗用您的云服务使用权。
说明：
开发环境：如果您在本地开发调试阶段，可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig。该方法中 secretKey 很容易被反编译逆向破解，一旦您的密钥泄露，攻击者就可以盗用您的腾讯云流量。
生产环境：如果您的项目要发布上线，请采用 服务端生成 UserSig 的方式。

步骤4: 设置昵称和头像 [可选]

首次登录的用户没有头像和昵称信息，您可以通过 setSelfInfo 接口设置头像和昵称：
setSelfInfo
Flutter（Dart）
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart

void _setSelfInfo() {
    String nickname = "jack"
    String avatar = "https:/****/user_avatar.png"
    CompletionHandler result = TUICallKit.instance.setSelfInfo(nickname, avatar);
}
参数
类型
说明
nickname
String
目标用户的昵称。
avatar
String
目标用户的头像。

步骤5: 发起通话

拨打方可以通过调用 calls 函数，并指定媒体类型和被叫方用户 ID 列表，来发起语音或视频通话。calls 接口同时支持一对一通话和多人通话。当 userIdList 中包含一个 userId 时，为一对一通话；当 userIdList 包含多个 userId 时，则为多人通话。
calls
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';
......

void _call() {
    List<String> participantIds = ['vince'];
    CallMediaType mediaType = CallMediaType.audio;
    CallParams callParams = CallParams();    
    TUICallKit.instance.calls(participantIds, mediaType, callParams);
}
参数
类型
说明
userIdList
List<String>
目标用户的 userId 列表。
mediaType
CallMediaType
通话的媒体类型，例如视频通话、语音通话。
params
CallParams
通话扩展参数，例如房间号、通话邀请超时时间，离线推送自定义内容等。

步骤6: 接听通话

接听端完成登录后，拨打端发起通话，接收端就可以收到通话邀请，同时伴随铃声和振动。

更多功能

AI 转录与翻译

您可以通过调用 enableAITranscriber 开启/关闭 AI 转录与翻译功能。

注意：
1. 该功能默认为开启状态（enable = true）。如需关闭，请在发起通话前调用 enableAITranscriber(enable: false)。
2. AI 实时转录与翻译为增值服务。体验版赠送免费额度，可直接体验。如需开通正式版，请在 实时音视频控制台 开通套餐包。
enableAITranscriber
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';

void _enableAITranscriber() {
    TUICallKit.instance.enableAITranscriber(true);
}
详情：默认为 true，通话界面上显示 AI 翻译相关页面，设置为 false 后关闭。

开启悬浮窗功能

您可以通过调用 enableFloatWindow 开启/关闭悬浮窗功能，在初始化 TUICallKit 组件时启用该功能，默认状态为关闭（false）。可通过点击通话界面左上角的悬浮窗按钮，将通话界面缩小为悬浮窗形式。

enableFloatWindow
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';
......

void _enableFloatWindow() {
    TUICallKit.instance.enableFloatWindow(true);
}
详情：默认为 false，通话界面左上角的悬浮窗按钮隐藏，设置为 true 后显示。

开启来电横幅

您可以通过调用 enableIncomingBanner 开启/关闭来电横幅显示，该功能默认为关闭状态（false）。当被叫端收到来电时，默认展示全屏通话等待界面。启用此功能后，将首先显示一个横幅通知，然后根据需要切换到全屏通话界面。请注意，显示来电横幅需要授予悬浮窗权限，具体的显示策略将根据权限设置及应用当前是否在前台或后台运行来决定。

enbalecomingBanner
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';
......

void _enableFloatWindow() {
    TUICallKit.instance.enableIncomingBanner(true);
}
详情：默认为 false，被叫端收到邀请后默认弹出全屏通话等待界面。开启后先展示一个横幅，然后根据需要拉起全屏通话界面。

多人通话

主叫方使用 calls 方法发起通话时，若被叫用户列表超过一人，则自动视为群组通话。其他成员可通过 join 方法加入该多人通话。
发起多人通话：使用 calls 方法发起通话时，若被叫用户列表（userIdList）超过一人，则自动视为群组通话。
calls
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';

void _call() {
    List<String> participantIds = ['vince','mike'];
    CallMediaType mediaType = CallMediaType.audio;
    CallParams callParams = CallParams();    
    TUICallKit.instance.calls(participantIds, mediaType, callParams);
}
参数
类型
说明
userIdList
List<String>
目标用户的 userId 列表。
mediaType
CallMediaType
通话的媒体类型，例如视频通话、语音通话。
params
CallParams
通话扩展参数，例如房间号、通话邀请超时时间，离线推送自定义内容等。
加入多人通话：可使用 join 方法加入指定的群组通话。
join
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';

void join() {
    String callId = "123456";
    TUICallKit.instance.join(callId);
}
参数
类型
说明
callId
String
此次通话的唯一标识。

语言设置

支持的语言：目前支持简体中文、英文和日文，默认语言为英文 。
切换语言：TUICallKit 不提供单独的语言切换接口。其界面语言将自动跟随当前应用程序根组件（如 MaterialApp 或 CupertinoApp）所使用的语言设置而切换。 您只需更改应用根组件的语言配置即可实现通话界面的语言切换。
说明：
如需设置其他语言，请联系我们（info_rtc@tencent.com）获取协助。

铃声设置

您可通过以下方式设置默认铃声、来电静音模式：
设置默认铃声：如果您通过源码依赖 TUICallKit 组件，您可以替换铃声资源文件（发起呼叫时的铃音、接到呼叫时的铃音）设置默认铃声。
来电静音模式：您可以通过 enableMuteMode 设置静音模式。
enableMuteMode
import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';
......

void _setCallingBell() {
    TUICallKit.instance.enableMuteMode(true);
}
详情：开启后，收到通话请求，不会播放来电铃声。

自定义您的 UI

替换图标按钮

您可以直接替换 assets/images 文件夹下的图标，以确保整个 App 中的图标色调风格保持一致。以下列出了基本的功能按钮，您可以替换对应的图标以适配自己的业务场景。

常见问题

如果您的接入和使用过程中遇到问题，请参见 常见问题。

交流与反馈

如果有任何需要或者反馈，您可以联系：info_rtc@tencent.com。
上一篇: Web&H5 (Vue3)下一篇: uniapp（Android&iOS）

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈