Run Demo

This document describes how to integrate the SDK for Unity.

Environment Requirements

Environment
Version
Unity
2019.4.15f1 or later
Android
Android Studio 3.5 or later; devices with Android 4.1 or later for apps
iOS
Xcode 11.0 or later. Ensure that your project has a valid developer signature.

Supported Platforms

We are committed to building a set of Chat SDK and TUIKit for all Unity platforms, allowing you to run one set of code on all platforms.
Platform
Chat SDK
iOS
Supported
Android
Supported
macOS
Supported
Windows
Supported
Supported from 1.8.1+
Note
For web, you need to perform a few extra steps for SDK integration. For details, see Part 5.

Prerequisites

1. You have signed up for a Tencent Cloud account and completed identity verification.
2. You have created an application as instructed in Creating and Upgrading an Application and recorded the SDKAppID.

Part 1. Creating Test Accounts

In the Chat console, select your application and click Auxiliary Tools > UserSig Generation & Verification on the left sidebar. Create two UserID values and their UserSig values, and copy the UserID, Key, and UserSig for subsequent logins.
Note
The test account is for development and testing only. Before the application is launched, the correct method for generating a UserSig is to integrate the UserSig calculation code into your server and provide an application-oriented API. When UserSig is needed, your application can send a request to the business server for a dynamic UserSig. For more information, see Generating UserSig.


Part 2. Integrating Chat SDK into Your Unity Project

1. Use Unity to create a project and record the project directory, or open an existing Unity project.
2. Open the project with an IDE (such as Visual Studio Code):

3. Find Packages/manifest.json based on the directory, and modify dependencies as follows:
{
"dependencies":{
"com.tencent.imsdk.unity":"https://github.com/TencentCloud/chat-sdk-unity.git#unity"
}
}
To help you better understand Chat SDK APIs, we provide API examples to demonstrate how to call APIs and trigger listeners.

Part 3. Loading Dependencies

Open the project in the Unity Editor, wait until dependencies are loaded, and confirm the Tencent Cloud Chat is successfully loaded.


Part 4. Implementing Your Own UI

Prerequisites

You have created a Unity project or have a project that can be based on Unity, and have loaded Tencent Cloud Chat SDK.

Initializing the SDK

Note:
To respect the copyright of emoji designs, the Chat Demo/TUIKit project does not include cutouts of large emoji elements. Please replace them with your own designs or other emoji packs for which you hold the copyright before officially launching for commercial use. The default smiley face emoji pack shown below is copyrighted by Tencent RTC and is available for licensed use for a fee. If you need to obtain a license, please contact us.



Call TencentIMSDK.Init to initialize the SDK.
Pass in your SDKAppID.
using Com.Tencent.IM.Unity.UIKit;
using com.tencent.imsdk.unity;
using com.tencent.imsdk.unity.types;
using com.tencent.imsdk.unity.enums;
namespace Com.Tencent.IM.Unity.UIKit{
public static void Init() {
string SDKAppID = ""; // Get the `SDKAppID` from the Chat console
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);
}
}

After Init, you can mount some listeners to the Chat SDK, mainly including those for network status and user information change. For more information, see here.

Logging in with a test account

Log in with one of the test accounts you created earlier.
Call the TencentIMSDK.Login method to log in with the test account.
If the returned res.code is 0, the login is successful.
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)=>{
// Process the login callback logic
});
}
Note
The test account is for development and testing only. Before the application is launched, the correct method for generating a UserSig is to integrate the UserSig calculation code into your server and provide an application-oriented API. When UserSig is needed, your application can send a request to the business server for a dynamic UserSig. For more information, see Generating UserSig.

Sending a message

The following shows how to send a text message:
Sample code:
public static void MsgSendMessage() {
string conv_id = ""; // The conversation ID of a one-to-one message is the `userID`, and that of a group message is the `groupID`.
Message message = new Message
{
message_conv_id = conv_id,
message_conv_type = TIMConvType.kTIMConv_C2C, // For a group message, this value is `TIMConvType.kTIMConv_Group`
message_elem_array = new List<Elem>
{
new Elem
{
elem_type = TIMElemType.kTIMElem_Text,
text_elem_content = "This is an ordinary text message"
}
}
};
StringBuilder messageId = new StringBuilder(128); // messageId for getting message ID when message is sent

TIMResult res = TencentIMSDK.MsgSendMessage(conv_id, TIMConvType.kTIMConv_C2C, message, messageId, (int code, string desc, string json_param, string user_data)=>{
// Async message sending result
});
// The message ID returned when the message is sent
}
Note
If sending fails, it may be that your sdkAppID doesn't support sending messages to strangers. In this case, you can disable the relationship check feature in the console.
Disable the friend relationship chain check here.


Obtaining the conversation list

Log in with the second test account to pull the conversation list.
The conversation list can be obtained in two ways:
1. Listen for the persistent connection callback to get message changes and update and render the historical message list in real time.
2. Call an API to get the message history at certain time points.
Common use cases include:
Getting the conversation list when the application starts and listening for the persistent connection callback to update the conversation list in real time.

Requesting the conversation list at certain time points

TIMResult res = TencentIMSDK.ConvGetConvList((int code, string desc, List<ConvInfo> info_list, string user_data)=>{
// Process the async logic
});
At this point, you can see the message sent by the first test account in the previous step.

Listening for the persistent connection to get the conversation list in real time

Mount the conversation list listener, process the callback event, and update the UI.
Mount the listener.
TencentIMSDK.SetConvEventCallback((TIMConvEvent conv_event, List<ConvInfo> conv_list, string user_data)=>{
// Process the callback logic
});
Process the callback event and display the latest conversation list on the UI.

Receiving messages

Messages can be received with the Chat SDK in two ways:
Listen for the persistent connection callback to get message changes and update and render the historical message list in real time.
Call an API to get the message history at certain time points.
Common use cases include:
After a new conversation is opened on the UI, request and display a certain number of historical messages.
Listen for the persistent connection to receive messages in real time and add them to the historical message list.

Requesting the historical message list at a time

To avoid affecting the pull speed, we recommend you limit the number of messages pulled to 20 per page.
You need to dynamically record the current number of pages for the next request.
Sample code:
// Pull historical one-to-one messages
// Do not set `msg_getmsglist_param_last_msg` for the first pull. It will pull the newest message if not set.
// `msg_getmsglist_param_last_msg` can be the last message in the returned message list for the second pull.
Message LastMessage = null;
string LastMessageID = "";
var get_message_list_param = new MsgGetMsgListParam();
TIMResult res = TencentIMSDK.MsgGetMsgList(conv_id, TIMConvType.kTIMConv_C2C, get_message_list_param, (params object[] parameters) => {
// handle callback logic
List<Message> messages = Utils.FromJson<List<Message>>((string)parameters[1]);
if (messages.Count > 0){
LastMessage = messages[messages.Count - 1];
LastMessageID.text = messages[messages.Count - 1].message_msg_id;
}else {
LastMessage = null;
LastMessageID.text = "";
}
});
// `msg_getmsglist_param_last_msg` can be the last message in the returned message list for the second pull.
var get_message_list_param = new MsgGetMsgListParam
{
msg_getmsglist_param_last_msg = LastMessage
};
TIMResult res = TencentIMSDK.MsgGetMsgList(conv_id, TIMConvType.kTIMConv_Group, get_message_list_param, (int code, string desc, string user_data) => {
// handle callback logic
});

Listening for the persistent connection callback to get new messages in real time

After the historical message list is initialized, new messages are from the persistent connection TencentIMSDK.AddRecvNewMsgCallback.
After the AddRecvNewMsgCallback callback is triggered, you can add new messages to the historical message list as needed.
Sample code for binding a listener:
TencentIMSDK.AddRecvNewMsgCallback((List<Message> message, string user_data) => {
// Process new messages
});
At this point, you have completed the Chat module development, and now users can send and receive messages and enter different conversations.
You can develop more features, such as group, user profile, relationship chain, and local search.
For more information, see Integration Solution (No UI).

Part 5. Enabling Unity Support for WebGL

Tencent Cloud Chat SDK for Unity 1.8.1 or later supports building WebGL.
To enable support for web, you need to perform the following extra steps in addition to those for enabling support for Android and iOS:

Importing JS

Download the JS files below from Npm (you need to install nodejs, please refer to the nodejs official website) and place them in the folder where the project builds WebGL products.
index.js
modules/group-moudle.js
modules/relationship-module.js
modules/signaling-module.js Open index.html and import the JS files as follows:
<script src="./index.js"></script>
<script src="./modules/group-module.js"></script>
<script src="./modules/relationship-module.js"></script>
<script src="./modules/signaling-module.js"></script>

FAQs

What platforms are supported?

iOS, Android, Windows, macOS, and WebGL are supported.

What should I do if clicking Build And Run for an Android device triggers an error, stating no available device is found?

Check that the device is not occupied by other resources. Alternatively, click Build to generate an APK package, drag it to the simulator, and run it.

What should I do if an error occurs during the first run for an iOS device?

If an error is reported for an iOS device after the demo configured as above is run, choose Product > Clean to clean the product, and build the demo again. You can also close Xcode and open it again, and then build the demo again.

What should I do if Unity v2019.04 reports the following error for iOS?

Library/PackageCache/com.unity.collab-proxy@1.3.9/Editor/UserInterface/Bootstrap.cs(23,20): error CS0117: 'Collab' does not contain a definition for 'ShowChangesWindow' Choose Window > Package Manager on the toolbar of the Editor and downgrade Unity Collaborate to 1.2.16.

What should I do if Unity v2019.04 reports the following error for iOS?

Library/PackageCache/com.unity.textmeshpro@3.0.1/Scripts/Editor/TMP_PackageUtilities.cs(453,84): error CS0103: The name 'VersionControlSettings' does not exist in the current context Open the source code and delete the code snippet of || VersionControlSettings.mode != "Visible Meta Files".

Is this a C# interface? How to use it without Unity?

Unity SDK is an SDK using C#, but because Unity SDK contains Unity features, it cannot be used directly in a C# environment.
If you need to use it in a C# environment, we provide a separate C# SDK nuget package. The usage method is the same as Unity SDK, you can refer to Unity SDK documentation for use.
Among them, the C# SDK only supports the PC side, and the unity SDK supports the mobile side.

Is there a UI that can be used directly?

The corresponding UIKit of untiy SDK and C# SDK is currently not provided.

How do I query error codes?

For Chat SDK API error codes, see Error Codes.