TUIKit is a UI component library based on Tencent Cloud Chat SDK. It provides some universal UI components, including conversations, chats, relationship chains, groups, audio/video calls, and other features. With these UI components, you can quickly build your own in-app chat.
While implementing UI features, the components in TUIKit will call the corresponding interfaces of the Chat SDK to implement Chat-related logic and data processing. Therefore, developers only need to focus on their own business or personalized expansion when using TUIKit.
Prerequisites
Enabling a Service
1. Log in to Chat and create an application. Click Create Application, input your Application name in the dialog box, select Product and Region, then click Create to create the application.
2. After creation, you can view the SDKAppID and SecretKey of the newly created app on the console overview page. These two pieces of info are required to run the Demo subsequently.
3. Create 2–3 preset accounts for experience in C2C chat and group chat.
4. Get userSig info via UserSign Tools for login account.
Environment Requirements
Vue (Fully compatible with both Vue2 & Vue3. While incorporating below, please select the Vue version guide that matches your needs)
TypeScript (Should your project be based on JavaScript, please proceed to JS project integrate to set up a progressive support for TypeScript)
Sass (sass-loader ≤ 10.1.1)
node(node.js ≥ 16.0.0)
npm (use a version that matches the Node version in use)
Integration of TUIKit
Step 1: Create Project
TUIKit supports the use of vite or vue-cli for project creation, configuring Vue3/Vue2 + TypeScript + sass. The following is several project setup examples:
vite
vue-cli
Note:
Vite requires Node.js version 18+ or 20+. When your package manager issues a warning, please note to upgrade your Node Version. For details, refer to vite official website.
Create a project using vite, configure Vue + TypeScript as shown in the figure below.
npm create vite@5
Then switch to the project directory and install the project dependencies:
cd chat-example
npminstall
Install the Sass environment dependency required for TUIKit:
npm i -D sass@1.77.0 sass-loader@10.1.1
Add the following compilation rule to the root directory file tsconfig.app.json:
typescript ≥ 5.0.0
typescript < 5.0.0
{
...
"compilerOptions":{
...
"verbatimModuleSyntax":false,
}
}
{
...
"compilerOptions":{
...
"importsNotUsedAsValues":"preserve",
}
}
Note:
If tsconfig.json uses references, the rule must be written in the referenced file (such as ./tsconfig.app.json), otherwise writing it in tsconfig.json does not take effect. The rule addition must be made to the actual references corresponding file. The following is a specific example:
Incorrect Writing Format
Correct Writing Format
When the tsconfig.json file contains existing references configuration, declaring the following rules directly in tsconfig.json is invalid.
When the tsconfig.json file contains existing references configuration, the following rules must be declared in the corresponding references internal file. Below is the configuration of the following rules in the root directory tsconfig.app.json file within references.
Note:
Note: Be sure to ensure your @vue/cli version is 5.0.0 or higher. You can use the following example code to upgrade your @vue/cli version to v5.0.8.
Create a project using vue-cli, configure Vue2/Vue3 + TypeScript + sass.
If you have not installed vue-cli or your vue-cli version is lower than 5.0.0, you can install it in terminal or cmd in the following ways:
On the page to be displayed, import the TUIKit component and it can be used.
Note:
To respect emoji design copyright, the Chat Demo/TUIKit project does not include large emoji element slicing. Before official commercial launch, please replace with other emoji packs designed or owned by oneself. The default little yellow face emoji pack is owned by Tencent Cloud, as shown below. You can upgrade to Chat Pro Edition Plus and Enterprise Edition to try it for free.
For example: Implement the following code in the App.vue page to quickly build a chat interface (the example code below supports both Web and H5):
Note:
Note: The following example code uses the setup syntax. If your project no longer uses the setup syntax, register the component according to the standard method for Vue3/Vue2.
If it is a project created with Vite, you can comment out the default invalid style in the project. You can delete useless content depending on the situation.
If it is a project created by vite, you can comment out the invalid style in the default project. You can delete useless content depending on the situation.
parallel:false,// disable thread-loader, which is not compactible with this plugin
configureWebpack:{
plugins:[
ScriptSetup({
/* options */
}),
],
},
chainWebpack(config){
// disable type check and let `vue-tsc` handles it
config.plugins.delete("fork-ts-checker");
},
};
4. At the end of the src/TUIKit/adapter-vue.ts file, replace the export source:
// initial writing
export*from"vue";
// replace with
export*from"@vue/composition-api";
If it is a project created by Vite, you can comment out the invalid style in the default project. You can delete useless content depending on the situation.
src/style.css
#app{
/* max-width: 1280px; */
margin: 0 auto;
/* padding: 2rem; */
text-align: center;
}
Step 4: Configure Authentication Information
Set the props App.vue in the TUIKit component: SDKAppID, userID, userSig.
Note:
UserSig is the password for user login to Chat, which is essentially the encrypted ciphertext of UserID and other information.
UserSig issuance method integrates the UserSig calculation code into your server and provides a project-oriented API. When UserSig is required, your project initiates request to the business server to obtain dynamic UserSig.
The example code in this document uses the method of obtaining UserSig by configuring SECRETKEY in client-side code. In this method, SECRETKEY can be easily decompiled and reverse-engineered. Once your key is leaked, attackers can misappropriate your Tencent Cloud traffic. Therefore, this method is only suitable for locally debugging features. For more details, see server-side generation of UserSig.
<TUIKit
:SDKAppID="0"// number
userID="xxx"// string
userSig="xxx"// string
/>
Step 5: Start Project
Execute the following command to start the project:
vite
vue-cli
npm run dev
Note:
Since vue-cli enables the global overlay error message prompt by default, for a better experience, it is recommended to disable the global overlay error prompt in vue.config.js or other webpack configuration files in your project.
Webpack4 and Above
webpack3
module.exports =defineConfig({
...
// Add new configuration code to disable overlay
devServer:{
client:{
overlay:false,
},
},
});
module.exports ={
...
// Add new configuration code to disable overlay
devServer:{
overlay:false,
},
};
npm run serve
Trial Basic Feature
Send Your First Message
1. After the project starts, click Initiate a Private Chat in the upper left corner.
2. Enter the Initiate a Private Chat popup. In the search box, input the userID created in "Enabling a Service", then click Complete once selected.
3. Enter the message in the input box and click Send.
Step example for sending your first message on the Web:
H5 steps to "send your first message":
Make Your First Phone Call
Add-Ons: Switch Language
Web & H5 Vue TUIKit comes with built-in Simplified Chinese, English language packs as interface display languages.
A UserSig is a password with which you can log in to use IM service. It is the ciphertext generated by encrypting information such as userID.
The issuance of UserSig is achieved by integrating the calculation code for UserSig into your server-side, whilst providing an interface designed for your project. Whenever UserSig is required, your project could request the operational server for a dynamic UserSig. For further information, please refer to Generating UserSig on the server-side.
Caution
The method to obtain UserSig demonstrated in this document utilizes the configuration of a SECRETKEY within the client-side code. Within this procedure, the SECRETKEY is notably vulnerable to decompilation and reverse-engineering. Should your SECRETKEY be leaked, malefactors could potentially exploit your Tencent Cloud traffic. Therefore, this technique is only appropriate for local operation and functional debugging. For the correct method of issuing UserSig, please refer to the earlier text.
Connection Errors FAQs
Runtime error: "TypeError: Cannot read properties of undefined (reading "getFriendList")"
If the following errors occur during runtime after connecting as per the steps outlined above, it is imperative that you delete the node_modules directory under the TUIKit folder to ensure the uniqueness of TUIKit's dependencies, preventing issues caused by multiple copies of dependencies.
How does a JS project integrate the TUIKit component?
TUIKit exclusively supports the TS environment for operation. You can enable the coexistence of existing JS code in your project with the TS code in TUIKit through progressive configuration of TypeScript.
vue-cli
vite
Please execute the following in the root directory of your engineering project created by the Vue CLI scaffold:
vue add typescript
Subsequently, please make selections in accordance with the following configuration options. To assure that we can support both the existing js code and the ts code within TUIKit, it is imperative that you strictly adhere to the five options presented below.
Once these steps are completed, please rerun the project!
Please execute the following command in your project's root directory created with vite:
The above error message appears because your installed @vue/cli version is too low. You must ensure that your @vue/cli version is 5.0.0 or higher. The upgrade method is as follows:
npm install -g @vue/cli@5.0.8
Runtime error: Failed to resolve loader: sass-loader
The above error message appears because the sass environment is not installed on your machine, please run the following command to install the sass environment:
npm i -D sass sass-loader@10.1.1
Other ESLint errors?
If copying chat-uikit-vue to the src directory results in error due to inconsistency with your local project code style, you may ignore this component directory. This can be achieved by adding .eslintignore file to the project root directory:
# .eslintignore
src/TUIKit
How to disable the full screen overlay error message prompt of webpack in dev mode in vue/cli?
You can disable it in the vue.config.js file at the root directory of your project:
webpack4
webpack3
module.exports =defineConfig({
...
devServer:{
client:{
overlay:false,
},
},
});
module.exports ={
...
devServer:{
overlay:false,
},
};
What to do when encountering 'Component name "XXXX" should always be multi-word'?
The version of ESLint utilized in IM TUIKit web is v6.7.2, which does not rigidly verify the camelCase format for module names.
Should you encounter this dilemma, you may configure as follows in the .eslintrc.js file:
module.exports ={
...
rules: {
...
'vue/multi-word-component-names':'warn',
},
};
What should I do if I encounter ERESOLVE unable to resolve dependency tree?
If ERESOLVE unable to resolve dependency tree appears when npm install is run, it indicates a conflict in dependency installation. The following method can be adopted for installation:
npminstall --legacy-peer-deps
How might one address the error message, 'vue packages version mismatch' occurring during execution?
// If you are using a vue2.7 project, please execute in your project root directory
npm i vue@2.7.9 vue-template-compiler@2.7.9
// If you have a Vue2.6 project, please execute in your project's root directory
npm i vue@2.6.14 vue-template-compiler@2.6.14
Why does TypeScript report an error after npm run build in a Vite project?
Reason: It's led by the vue-tsc command in "build": "vue-tsc && vite build" under package.json script.
