tencent cloud

TUIKit 从 5.7.1435 版本开始支持模块化集成，您可以根据自己的需求集成所需模块。
TUIKit 从 6.9.3557 版本开始新增了全新的简约版 UI，之前的 UI 依旧保留，我们称之为经典版 UI，您可以根据需求自由选择经典版或简约版 UI。

如果您还不了解各个界面库的功能，可以查阅文档 TUIKit 界面库介绍。

下文将介绍如何集成 TUIKit 组件。

开发环境要求

• Android Studio-Chipmunk

• Gradle-6.7.1

• Android Gradle Plugin Version-4.2.0

• kotlin-gradle-plugin-1.5.31

  module 源码集成

1. 从 GitHub 下载 TUIKit 源码。使 TUIKit 文件夹跟自己的工程文件夹同级，例如：
2. 根据实际业务需求在 settings.gradle 中添加对应的 TUI 组件。TUI 组件之间相互独立，添加或删除均不影响工程编译。

   // 引入上层应用模块
   include ':app'
   
   

// 引入音视频通话功能模块
include ':tuicallkit'
project(':tuicallkit').projectDir = new File(settingsDir, '../TUIKit/TUICallKit/tuicallkit')


3. 在 APP 的 build.gradle 中添加：

   dependencies {
    api project(':tuiconversation')
    api project(':tuicontact')
    api project(':tuichat')
    api project(':tuisearch')
    api project(':tuigroup')
    api project(':tuiofflinepush')
    api project(':tuicommunity')
    api project(':tuicallkit')  
   }
   

4. 在 gradle.properties 文件中加入下行，表示自动转换三方库以兼容 AndroidX：

   android.enableJetifier=true
   

5. 添加 maven 仓库 和 Kotlin 支持，在 root 工程的 build.gradle 文件（与 settings.gradle 同级）中添加：

buildscript {
    ext.kotlin_version = '1.5.31'
    repositories {
        mavenCentral()
        maven { url "https://mirrors.tencent.com/nexus/repository/maven-public/" }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:4.2.0'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

6. 同步工程，编译运行。工程结构预期效果如图所示：
   
7. 裁剪不需要的 UI 文件（可选）
   经典版和简约版 UI 互不影响，可独立运行。经典版和简约版的 UI 文件都在各 TUI 组件中，放在不同的文件夹里，以 TUIChat 组件为例： classicui 文件夹中存放的是`经典版` UI 文件，minimalistui 文件夹中存放的是`简约版` UI 文件, 如果您要集成简约版 UI，可直接删除 classicui 文件夹，同时删除 AndroidManifest.xml 文件中经典版 UI 对应的 Activity 和 Service 。 > ? 经典版和简约版 UI 不能混用，集成多个组件时，您必须同时选择经典版 UI 或者 简约版 UI。

快速搭建

常用的聊天软件都是由会话列表、聊天窗口、好友列表、音视频通话等几个基本的界面组成，参考下面步骤，您仅需几行代码即可在项目中快速搭建这些 UI 界面。

步骤1：组件登录

// 在用户 UI 点击登录的时候调用
TUILogin.login(context, sdkAppID, userID, userSig, new TUICallback() {
    @Override
    public void onError(final int code, final String desc) {
    }

    @Override
    public void onSuccess() {
    }
});

注意：

context 必须传 Application 对象，否则部分图片无法加载。

步骤2：创建 viewPager

1. 在 activity_main.xml 中添加界面布局：

   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">
    
    <androidx.viewpager2.widget.ViewPager2
    android:id="@+id/view_pager"
    android:layout_width="match_parent"
    android:layout_height="0dp"
    android:layout_weight = "1"/>
   </LinearLayout>
   

2. 创建 FragmentAdapter.java 用来配合 ViewPager2 展示会话和联系人界面。

   import androidx.annotation.NonNull;
   import androidx.fragment.app.Fragment;
   import androidx.fragment.app.FragmentActivity;
   import androidx.fragment.app.FragmentManager;
   import androidx.lifecycle.Lifecycle;
   import androidx.viewpager2.adapter.FragmentStateAdapter;
   
   
   

<span class="hljs-keyword">private</span> List&lt;Fragment> fragmentList;

<span class="hljs-function"><span class="hljs-keyword">public</span> <span class="hljs-title">FragmentAdapter</span><span class="hljs-params">(<span class="hljs-meta">@NonNull</span> FragmentActivity fragmentActivity)</span> </span>{
    <span class="hljs-keyword">super</span>(fragmentActivity);
}

<span class="hljs-function"><span class="hljs-keyword">public</span> <span class="hljs-title">FragmentAdapter</span><span class="hljs-params">(<span class="hljs-meta">@NonNull</span> Fragment fragment)</span> </span>{
    <span class="hljs-keyword">super</span>(fragment);
}

<span class="hljs-function"><span class="hljs-keyword">public</span> <span class="hljs-title">FragmentAdapter</span><span class="hljs-params">(<span class="hljs-meta">@NonNull</span> FragmentManager fragmentManager, <span class="hljs-meta">@NonNull</span> Lifecycle lifecycle)</span> </span>{
    <span class="hljs-keyword">super</span>(fragmentManager, lifecycle);
}

<span class="hljs-function"><span class="hljs-keyword">public</span> <span class="hljs-keyword">void</span> <span class="hljs-title">setFragmentList</span><span class="hljs-params">(List&lt;Fragment> fragmentList)</span> </span>{
    <span class="hljs-keyword">this</span>.fragmentList = fragmentList;
}

<span class="hljs-meta">@NonNull</span>
<span class="hljs-meta">@Override</span>
<span class="hljs-function"><span class="hljs-keyword">public</span> Fragment <span class="hljs-title">createFragment</span><span class="hljs-params">(<span class="hljs-keyword">int</span> position)</span> </span>{
    <span class="hljs-keyword">if</span> (fragmentList == <span class="hljs-keyword">null</span> || fragmentList.size() &lt;= position) {
        <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> Fragment();
    }
    <span class="hljs-keyword">return</span> fragmentList.get(position);
}

<span class="hljs-meta">@Override</span>
<span class="hljs-function"><span class="hljs-keyword">public</span> <span class="hljs-keyword">int</span> <span class="hljs-title">getItemCount</span><span class="hljs-params">()</span> </span>{
    <span class="hljs-keyword">return</span> fragmentList == <span class="hljs-keyword">null</span> ? <span class="hljs-number">0</span> : fragmentList.size();
}

}


步骤3：构建核心 Fragment

会话列表 TUIConversationFragment 以及联系人列表 TUIContactFragment 界面数据的获取、同步、展示以及交互均已在组件内部封装，UI 的使用与 Android 的普通 Fragment 一样方便。

在 MainActivity.java 的 onCreate 方法中添加以下代码：

List<Fragment> fragments = new ArrayList<>();
// 添加 tuiconversation 组件提供的经典版会话界面
fragments.add(new TUIConversationFragment());

// 添加 tuicontact 组件提供的经典版联系人界面
fragments.add(new TUIContactFragment());
ViewPager2 mainViewPager = findViewById(R.id.view_pager);
FragmentAdapter fragmentAdapter = new FragmentAdapter(this);
fragmentAdapter.setFragmentList(fragments);
mainViewPager.setOffscreenPageLimit(2);
mainViewPager.setAdapter(fragmentAdapter);
mainViewPager.setCurrentItem(0, false);

List<Fragment> fragments = new ArrayList<>();
// 添加 tuiconversation 组件提供的简约版会话界面
fragments.add(new TUIConversationMinimalistFragment());

// 添加 tuicontact 组件提供的简约版联系人界面
fragments.add(new TUIContactMinimalistFragment());
ViewPager2 mainViewPager = findViewById(R.id.view_pager);
FragmentAdapter fragmentAdapter = new FragmentAdapter(this);
fragmentAdapter.setFragmentList(fragments);
mainViewPager.setOffscreenPageLimit(2);
mainViewPager.setAdapter(fragmentAdapter);
mainViewPager.setCurrentItem(0, false);

步骤4：构建音视频通话功能

TUI 组件支持在聊天界面对用户发起音视频通话，仅需要简单几步就可以快速集成：

视频通话	语音通话

1. 开通音视频服务

   1. 登录 即时通信 IM 控制台 ，单击目标应用卡片，进入应用的基础配置页面。
   2. 在开通腾讯实时音视频服务功能区，单击免费体验即可开通 TUICallKit 的 7 天免费试用服务。
   3. 在弹出的开通实时音视频 TRTC 服务对话框中，单击确认，系统将为您在 实时音视频控制台 创建一个与当前 IM 应用相同 SDKAppID 的实时音视频应用，二者帐号与鉴权可复用。

2. 集成 TUICallKit 组件
   在 APP 的 build.gradle 文件中添加对 TUICallKit 的依赖：

   api project(':tuicallkit')
   

3. 发起和接收视频或语音通话

   消息页发起通话	联系人页发起通话

   • 集成 TUICallKit 组件后，聊天界面和联系人资料界面默认会显示 “视频通话” 和 “语音通话” 两个按钮，当用户点击按钮时，TUIKit 会自动展示通话邀请 UI，并给对方发起通话邀请请求。
   • 当用户在线并且应用在前台时收到通话邀请时，TUIKit 会自动展示通话接收 UI，用户可以选择同意或则拒绝通话。
   • 当用户离线收到通话邀请时，如需唤起 App 通话，需要使用离线推送能力。离线推送的实现请参考下一步。

4. 添加离线推送：
   实现音视频通话的离线推送，请参考以下几个步骤：

   1. 配置 App 的 离线推送。
   2. 集成 TUICallKit 组件。
   3. 通过 TUICallKit 发起通话邀请的时候，默认会生成一条离线推送消息。

5. 附加增值能力
   集成 TUIChat 和 TUICallkit 的组件后，在聊天界面发送语音消息时，即可录制带 AI 降噪和自动增益的语音消息。该功能需要购买 音视频通话能力进阶版及以上套餐，仅 IMSDK 7.0 及以上版本支持。当套餐过期后，录制语音消息会切换到系统 API 进行录音。
   下面是使用两台华为 P10 同时录制的语音消息对比：

   系统录制的语音消息	TUICallkit 录制的带 AI 降噪和自动增益的语音消息

开启文本消息翻译功能

文本消息翻译功能指的是，当您进入了聊天界面后，可以手动长按消息列表中的文本消息 item，在出现的菜单中，点击【翻译】按钮，翻译文本。
为了避免对用户使用造成影响，翻译功能默认关闭，消息长按菜单中不会出现【翻译】按钮。

如果您想使用翻译功能，需要操作以下两步：

1. 文本翻译是增值付费功能，按翻译字符数量计费。当前此功能处于内测阶段，请联系腾讯云商务为您开通。未开通服务的情况下，即使您在 UI 上显示了【翻译】按钮，也无法正常翻译。
2. 开通服务后，您可以在初始化聊天窗口前，设置显示【翻译】按钮，示例代码如下：

   // 显示翻译按钮
   TUIChatConfigs.getConfigs().getGeneralConfig().setEnableTextTranslation(true);
   

注意：

1. 文本消息翻译功能从 TUIChat 7.0 版本开始支持。
2. 仅支持文本消息、文本类的引用或回复消息，图片、语音、视频、文件、表情、自定义消息等不支持翻译。
3. 点击【翻译】后，会将文本翻译成当前 TUIChat 所使用的语言。例如当前 TUIChat 语言为英文，无论待翻译的文本是什么语言，都将被翻译为英文。

开启翻译服务及显示开关前后效果图如下所示：

• 经典版
• 简约版

不显示翻译按钮	显示翻译按钮	文本消息翻译效果

不显示翻译按钮	显示翻译按钮	文本消息翻译效果

常见问题

提示 "Manifest merger failed : Attribute application@allowBackup value=(true) from AndroidManifest.xml" 如何处理？

IM SDK 中默认 allowBackup 的值为 false ，表示关闭应用的备份和恢复功能。
您可以在您的 AndroidManifest.xml 文件中删除 allowBackup 属性，表示关闭备份和恢复功能；也可以在 AndroidManifest.xml 文件的 application 节点中添加 tools:replace="android:allowBackup" 表示覆盖 IM SDK 的设置，使用您自己的设置。

例如：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.tencent.qcloud.tuikit.myapplication">

    <application
        android:allowBackup="true"
        android:name=".MApplication"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.MyApplication"
        tools:replace="android:allowBackup">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

提示 "NDK at /Users/***/Library/Android/sdk/ndk-bundle did not have a source.properties file" 如何处理？

只需要在 local.properties 文件中加入您的 NDK 路径，例如：
ndk.dir=/Users/***/Library/Android/sdk/ndk/16.1.4479499

提示 "Cannot fit requested classes in a single dex file" 如何处理？

出现此问题可能是您的 API 级别设置比较低，需要在 App 的 build.gradle 文件中开启 MultiDex 支持, 添加 multiDexEnabled true 和对应依赖：

android {
    defaultConfig {
        ...
        minSdkVersion 19
        targetSdkVersion 30
        multiDexEnabled true
    }
    ...
}
dependencies {
    implementation "androidx.multidex:multidex:2.0.1"
}

同时，在您的 Application 文件中添加以下代码：

public class MyApplication extends SomeOtherApplication {
    @Override
    protected void attachBaseContext(Context base) {
        super.attachBaseContext(base);
        MultiDex.install(this);
    }
}

提示 "Plugin with id 'kotlin-android' not found." 如何处理？

因为 TUIChat 组件使用了 Kotlin 代码，所以需要添加 Kotlin 构建插件。请参考 module 源码集成第 5 步。