tencent cloud

即时通信 IM

Unity

下载
聚焦模式
字号
最后更新时间: 2026-04-28 14:21:51
Chat Unity UIKit 和 UIKit Demo 是基于 Tencent Cloud Chat SDK 实现的游戏场景业务 UI 组件库,目前包含了会话(Conversation) 和聊天 (Chat)组件,收发文字消息、收发表情包消息、自定义表情包等功能,支持 iOS 及 Android 平台。在您的 Unity 项目下引用此 UIKit 可助您快速搭建您的聊天系统。

环境要求

平台
版本
Unity
2019.4.15f1 及以上版本。
Android
Android Studio 3.5及以上版本,App 要求 Android 4.1及以上版本设备。
iOS
Xcode 11.0及以上版本,请确保您的项目已设置有效的开发者签名。

前提条件

开通服务

1. 登录 控制台。如果您已有应用,请记录其 SDKAppID 及 SDKSecretKey 并直接跳转到下一节。
2. 在概览面板单击创建,开始创建新应用。

3. 在创建应用弹框中填入应用名称,选择产品为 Chat。

4. 选择完产品后,会显示出部署区域,请按需选择。

5. 创建完成后,可在控制台概览面板查看新建应用的 SDKAppID、SDKSecretKey,后续运行 Demo 时需要用到这两个信息。

禁止:
请妥善保管 SDKSecretKey,谨防泄露!
6. 进入 UserSig 工具,选择刚才创建的应用,输入 UserID,会生成对应的 UserSig,复制信息,后续登录会使用到。


如何将 UIKit 导入到项目中

导入 AssetPackage

1. 创建/启动已存在的 Unity 项目。
2. 在 Packages/manifest.json 文件中的 dependencies 下添加:
{
"dependencies":{
"com.tencent.imsdk.unity":"https://github.com/TencentCloud/chat-sdk-unity.git#unity"
}
}
3. 下载 UIKit GitHub 目录下的 chat-uikit-unity.unitypackage,并导入资源包。

初始化并登录

初始化并登录 Chat 有两种方式:
方式一:组件外部
整个应用初始化并登录一次即可。需要自行添加相应的事件回调。
方式二:组件内部
通过配置的方式将参数传入组件内部。建议您使用内部登录,UIKit 已帮您绑定了相应的事件回调,包括接收新消息的事件以及会话列表更新的事件。
方式 1: 组件外部
在您创建的 Unity 项目中初始化 Chat,注意 Chat 应用只需初始化一次即可。如果在现有 Chat 项目中集成可跳过该步骤。
public static void Init() {
int sdkappid = 0; // 从即时通信 IM 控制台获取应用 SDKAppID。
SdkConfig sdkConfig = new SdkConfig();

sdkConfig.sdk_config_config_file_path = Application.persistentDataPath + "/TIM-Config";

sdkConfig.sdk_config_log_file_path = Application.persistentDataPath + "/TIM-Log"; // 设置本地日志地址

TIMResult res = TencentIMSDK.Init(long.Parse(sdkappid), sdkConfig);
}

public static void Login() {
if (userid == "" || user_sig == "")
{
return;
}
TIMResult res = TencentIMSDK.Login(userid, user_sig, (int code, string desc, string json_param, string user_data)=>{
// 处理登录回调逻辑
});
方式 2: 组件内部
您也可以将 SDKAppID、UserSig、UserID 通过配置的方式传入组件内部进行 Chat 的初始化和登录(与 demo 运行方式相同)。
using com.tencent.imsdk.unity.uikit;
// demo 登录逻辑如下
public static void Init() {
Core.SetConfig(sdkappid, userId, sdkUserSig);
Core.Init();
Core.Login();
}

// 若直接跑unity demo,推荐通过 Main 页面的手机号/验证码输入框登录。可以保证监听回调等正常运行。
// 由于电脑端unity不支持手机号登录,请将 userid输入到手机号输入框,userSig输入到验证码输入框。
// Assets/Example/Scripts/Main.cs
private void Login()
{
// 将之前的Login函数内容注释掉,添加以下内容
loginButton.interactable = false;
Core.SetConfig(Config.sdkappid, phoneNumber.text, captcha.text);
Core.Init();
Core.Login(HandleAfterLogin);
loginButton.interactable = true;
}

使用 Conversation 和 Chat 预制件

您可将下列预制件放入您的场景中,修改相应样式和布局(layout)。




项目结构

Assets/Example
该目录对应实际项目运行时显示的内容,包含 Scenes 的两个页面,分别对应的代码为Main.cs(登录界面) 和 Chat.cs(聊天界面)。
Chat 里包含单聊、群聊的内容,可以获取到会话(好友)列表并发送文字、表情包消息。Chat 里的内容由 Prefabs 里的组件构成,可以通过修改 Prefabs 修改显示内容和样式。
Assets/Prefabs
下列组件可以联合使用(参考 Scenes 的 Chat 页面),也可根据需求将组件单独修改并使用。
ChatPanel 消息历史列表
消息展示区 ConvMessagePanel
会话名展示区 ConversationNamePanel
历史消息展示区 MessageContentPanel
消息输入区 ActionPanel
表情包区 OverlayPanel
关闭聊天窗口按钮 CloseButton



ConversationPanel 会话列表。现主要显示好友的单聊会话。相应代码在 Script/Components/Conversation.cs 里。每个会话的样式在 ConversationItem.prefabs 里。
会话列表区 FriendPanel
搜索区 SearchPanel
会话列表 ConversationListPanel



ChannelPanel
频道列表,由4个频道按钮组成,分别为世界、频道、组队、好友。其中前三个频道为群聊频道,好友频道为单聊频道并会显示单聊会话列表。频道按钮的点击事件和样式在 Script/Components/Chat.cs 里。
AvatarPanel
会话(ConversationItem)、单条聊天记录(messageItem 等)里的头像样式。包含头像和段位头像。
ConversationItem
会话列表中的会话样式,包含头像(AvatarPanel),会话名称以及段位。
MessageItem、MessageItemSelf 文字消息内容。分别为他人发送文字消息和自己发送文字消息。
头像区 MessageSenderPanel
消息区 MessageContentPanel
发送者信息区 SenderNamePanel
发送者名字 MessageSender
发送者段位 Icon 和名称 Icon 和 Text
消息体 Panel
StickerMessageItem、StickerMessageSelf
表情包消息内容。内容与 MessageItem 相同。
GroupTipItem
群提醒消息内容,为用户进群、退群、admin 消息等。包含群名和消息体。
TimeStamp 历史消息中的时间节点。
StickerItem、MenuItem
分别为表情包和快捷 menu 里的表情包。

如何启动 Demo 项目

初始化登录

将 SDKAppID、UserSig、UserID 通过配置的方式传入组件内部进行 Chat 的初始化和登录。
注意:
整个项目只需要初始化一次。
using com.tencent.imsdk.unity.uikit;
// demo 登录逻辑如下
public static void Init() {
Core.SetConfig(sdkappid, userId, sdkUserSig);
Core.Init();
Core.Login();
// 可传递函数
// Core.Login(HandleAfterLogin);
}

// 若直接跑unity demo,推荐通过 Main页面的手机号/验证码输入框登录。可以保证监听回调等正常运行。
// 由于电脑端unity不支持手机号登录,请将 userid输入到手机号输入框,userSig输入到验证码输入框。
// Assets/Example/Scripts/Main.cs
private void Login()
{
// 将之前的Login函数内容注释掉,添加以下内容
loginButton.interactable = false;
Core.SetConfig(Config.sdkappid, phoneNumber.text, captcha.text);
Core.Init();
Core.Login(HandleAfterLogin);
loginButton.interactable = true;
}
初始化登录后直接打开 Chat 页面即可。

频道

demo 中分世界、频道、组队、好友四个频道。其中 好友 频道显示 C2C 会话和已添加的好友的列表,点击某个会话可开始聊天。
其他三个频道为群组会话,若需要在该频道发消息则需要先创建群组并将其 ID 添加到项目中。

创建群组

通过 RestAPI 添加
您可以通过后台 RestAPI 中create_group创建群组。具体可见 链接。
在控制台添加
您也可以通过控制台创建群组。进入控制台中您的 Chat 应用 > 群组管理 > 添加群组。

将群组添加到频道

进入 Assets/Example/Scripts/Config/Config.cs,将创建的群组的群组 ID 填入 communityID(社群),channelID(频道),groupID(组队)。
并在登录之后调用 joinGroup 即可实现登录后进入相应群组,并可以在群内发送消息。

发送消息

若您已将群组添加到频道中,您可以通过世界、频道、组队频道发送群聊消息。
您也可以在好友频道点击某个单聊会话发送单聊消息。

修改表情包和段位信息

段位

现各个用户段位为随机生成,若您需要使用段位信息,您可以在用户的自定义字段中进行设置。
UserProfileCustemStringInfo teer = new UserProfileCustemStringInfo{
user_profile_custom_string_info_key:"段位",
user_profile_custom_string_info_value:"teer"
}
List<UserProfileCustemStringInfo> customArray = new List<UserProfileCustemStringInfo>();
customArray.Add(teer);
TencentIMSDK.ProfileModifySelfUserProfile(new UserProfileItem{
user_profile_item_custom_string_array:customArray;
});
并按照段位的名称显示相应的段位图标。
1. 将段位对应的图标或者头像框加载到 Resources 里。(若使用 Url 获取时可忽略这一步)
2. 修改代码中头像框和图标的显示。需要修改的部分为会话列表和消息列表。
3. 会话列表。
4. 在获取会话的函数 completeConvList 中补充获取到的段位信息。最终显示的好友会话信息在 friendProfiles 列表中。
5. 在 Conversation.cs 中的 GenerateList(会话列表渲染)中修改渲染的图标和头像。
6. 消息列表。
7. 在 Chat.cs 的 RenderMessageForScroll 中获取消息发送者的信息中的段位信息(若需要修改其他显示内容,也可以从这里获取)
8. 在 MsgItem.cs 中修改显示的样式等细节内容。

表情包

表情包使用 StickerPanel 显示在 Chat.cs 里的 OverlayPanel 中。您可以导入自己的表情包使用。(需要您提前导入自己的表情包)
1. 在 Assets/Resources 文件夹内导入所用的表情包图片:



2. 更改图片的 Texture Type 为 Sprite (2D and UI),并根据图片尺寸修改 Pixels Per Unit:



3. 定义相应的表情包数据:
// 生成表情包列表,StickerPackage 为一组表情包
List<StickerPackage> stickers = new List<StickerPackage> {
new StickerPackage {
name = "4350",
baseUrl = "custom_sticker_resource/4350", //Resource 文件夹内相对路径
menuItem = new StickerItem { // 表情栏表情项目
name = "menu@2x",
index = 0,
},
stickerList = new List<StickerItem> { // 表情包项目组
new StickerItem { // 具体表情包数据
name = "menu@2x",
index = 0 // 表情包顺序
},
}
}
};
4. 注册表情包给 UIKit:
using com.tencent.imsdk.unity.uikit;

Core.SetStickerPackageList(Config.stickers);

语言包

Chat Unity UIKit Demo 提供根据系统语言切换语言系统,现支持简体中文和英语。您可以按照需求增加语言或者修改里面的配置。
1. 语言资料 语言资料放在 Resources/LanguageTxt 里。现在包含 Chinese.txt(简体中文) 和 English.txt(英文)。若需要其他语言,可以添加对应的 txt 文件。
2. 该文件的结构如下:
//English.txt
Key:Value

//Chinese.txt
Key:值
注意:
1. Key 应与其他语言的 Key 一致,并与后续的 enum 一致。
2. Value 为 Key 对应的该语言的值。
3. Key 和 Value 之间使用冒号分隔开。
3. 设置语言
4. 设置语言和词条
5. 若你添加了语言,添加相应的语言词汇 txt 文件后在 LanguageDataManager.cs 中的 Language 中添加新的语言,并在 LanguageTextName 中增加对应的词条的 Key。
6. 加载语言词条文件
private Dictionary<string,string> EnglishDictionary = new Dictionary<string,string>();
LoadLanguageTxt(Language.English);
7. 组件设置(静态修改)
在需要设置的 text 组件中添加 LanguageUIText(Script) component,将需要显示的词的 Key 选中。改显示的 Key 对应 LanguageTextName 中的 enum 和词汇文件里的 Key。

8. 设置语言
若要设置语言,在软件开启时调用 SetCurrentLanguageValue。若要固定语言,可直接在 LanguageDataManager.cs 对 currentLanguage 赋值(可当成默认语言)。该 Demo 根据系统语言判断并赋值。若需要修改的组件不仅为静态组件,则简单的方法为将现在使用的语言保存到 config 中(在 Demo 中保存到了 Core)在代码中判断显示。

API 文档

SetConfig

在 Init 前传入 Config 信息,包括 sdkappid, userid 以及 usersig。
using com.tencent.imsdk.unity.uikit;

Core.SetConfig(sdkappid, userid, usersig);

Init

采用 UIKit 提供的 Init 方法来初始化 SDK,会自动绑定 AddRecvNewMsgCallback 和 SetConvEventCallback 回调。
using com.tencent.imsdk.unity.uikit;

Core.Init();

SetStickerPackageList

通过 SetStickerPackageList 设定表情包列表。
using com.tencent.imsdk.unity.uikit;

Core.SetStickerPackageList(Config.stickers);

Login

通过 Login 登录账号,登录完成后执行绑定的回调函数。
using com.tencent.imsdk.unity.uikit;

Core.Login((params string[] args) => {
// 处理Login回调
});

SetMessageList

添加某个会话的消息列表,处理后合并到当前会话消息字典里,并触发 OnMsgListChanged 事件。
using com.tencent.imsdk.unity.uikit;

Core.SetMessageList(currentConvID, newMsgList, isFinished);

SetCurrentConv

设置当前选中的会话,并触发 OnCurrentConvChanged 事件。
using com.tencent.imsdk.unity.uikit;

Core.SetMessageList(convID, convType);

SetCurrentStickerIndex

设置当前选中的表情包组,并触发 OnCurrentStickerIndexChanged 事件。
using com.tencent.imsdk.unity.uikit;

Core.SetMessageList(stickerIndex);

Logout

登出,并清空数据。
using com.tencent.imsdk.unity.uikit;

Core.Logout((string[] parameters) => {
// 处理Logout回调
});

TencentIMSDK

Unity TencentIMSDK 提供了基于 Unity 平台的全面的即时通信能力。您可以使用 TencentIMSDK 来获取其他即时通信的相关功能。例如通过 TencentIMSDK 来获取用户资料。
using com.tencent.imsdk.unity;

// 获取个人资料
FriendShipGetProfileListParam param = new FriendShipGetProfileListParam
{
friendship_getprofilelist_param_identifier_array = new List<string>
{
"self_userid"
}
};

TIMResult res = TencentIMSDK.ProfileGetUserProfileList(param, (int code, string desc, List<UserProfile> profile, string user_data)=>{
// 处理异步逻辑
});

常见问题

表情包的使用

为尊重表情设计版权,Chat Demo/TUIKit 工程中不包含大表情元素切图,正式上线商用前请您替换为自己设计或拥有版权的其他表情包。下图所示默认的小黄脸表情包版权归腾讯云所有,您可以通过升级至 Chat 专业版 Plus 和企业版 免费使用该表情包。




帮助和支持

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

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

文档反馈