uniapp
Introduction to chat-uikit-uniapp
chat-uikit-uniapp (vue2 /vue3) is a uniapp UI component library based on Tencent Cloud Chat SDK. It provides universally used UI components that include Conversation, Chat, and Group components. Leveraging these meticulously crafted UI components, you can quickly construct an elegant, reliable, and scalable Chat application. The interface of chat-uikit-uniapp is as demonstrated in the image below:
Supported Platform
Android
iOS
WeChat Mini Program
H5
Environment Requirements
HBuilderX (HBuilderX Version >= 3.8.4.20230531) or upgrade to the newest version
Vue2 / Vue3
Sass (sass-loader version ≤ 10.1.1)
Node (12.13.0 ≤ node version ≤ 17.0.0. The official LTS version 16.17.0 of Node.js is recommended.)
npm (use a version that matches the Node version in use)
TUIKit Source Code Integration
Follow the steps below to send your inaugural message.
Step 1: create a project (ignore this step if already has project)
Launch HbuilderX, select "File-New-Project" in the menu bar, and create a uni-app project named
chat-example
.
Step 2. Download the TUIKit component
Since HBuilderX does not create package.json files by default, you need to proactively create one. Execute the following command in the root directory of the project:
npm init -y
Download TUIKit and copy it to the source code:
npm i @tencentcloud/chat-uikit-uniapp unplugin-vue2-script-setup
For ease of subsequent extensions, we propose that you replicate the TUIKit component to the pages directory within your project. Please conduct the following command in the root directory of your own project:
mkdir -p ./TUIKit && rsync -av --exclude={'node_modules','package.json','excluded-list.txt'} ./node_modules/@tencentcloud/chat-uikit-uniapp/ ./TUIKit
mkdir -p ./TUIKit/tui-customer-service-plugin && rsync -av ./node_modules/@tencentcloud/tui-customer-service-plugin/ ./TUIKit/tui-customer-service-plugin
npm i @tencentcloud/chat-uikit-uniapp unplugin-vue2-script-setup
For ease of subsequent extensions, we propose that you replicate the TUIKit component to the pages directory within your project. Please conduct the following command in the root directory of your own project:
xcopy .\node_modules\@tencentcloud\chat-uikit-uniapp .\TUIKit /i /e /exclude:.\node_modules\@tencentcloud\chat-uikit-uniapp\excluded-list.txt
xcopy .\node_modules\@tencentcloud\tui-customer-service-plugin .\TUIKit\tui-customer-service-plugin /i /e
Step 3: Incorporate the TUIKit component
1. Project Configuration
In the root directory, create vue.config.js (For Vue3 projects, please disregard this part).
const ScriptSetup = require('unplugin-vue2-script-setup/webpack').default;module.exports = {parallel: false,configureWebpack: {plugins: [ScriptSetup({/* options */}),],},chainWebpack(config) {// disable type check and let `vue-tsc` handles itconfig.plugins.delete('fork-ts-checker');},};
Activate the split package configuration in the source code view of the
manifest.json
file{"mp-weixin": {"appid": "","optimization": {"subPackages": true}},"h5": {"optimization": {"treeShaking": {"enable": false}}}}
2. Merge TUIKIt
Note:
Pursue the integration stringently in Four Steps. If you wish to package a Mini Program, please do not bypass the configuration of the "Home page of Mini Program Sub-package".
Pay heed, under Vue2 environment, make use of
Vue.use(VueCompositionAPI)
, to prevent inability to use environment variables such as isPC
.// Introduce the main package dependencyimport TencentCloudChat from "@tencentcloud/chat";import TUICore from "@tencentcloud/tui-core";import App from './App';// #ifndef VUE3import Vue from 'vue';import './uni.promisify.adaptor';import VueCompositionAPI from "@vue/composition-api";Vue.use(VueCompositionAPI);Vue.config.productionTip = false;App.mpType = 'app';const app = new Vue({...App,});app.$mount();// #endif// #ifdef VUE3import { createSSRApp } from 'vue';export function createApp() {const app = createSSRApp(App);return {app,};}// #endif
{"pages": [{"path": "pages/index/index" // Your project's homepage}],"subPackages": [{"root": "TUIKit","pages": [{"path": "components/TUIConversation/index","style": {"navigationBarTitleText": "Tencent Cloud IM"}},{"path": "components/TUIChat/index","style": {"navigationBarTitleText": "Tencent Cloud IM"}},// To integrate the chat component, this path must be configured: video playback{"path": "components/TUIChat/video-play","style": {"navigationBarTitleText": "Tencent Cloud IM"}},{"path": "components/TUIChat/web-view","style": {"navigationBarTitleText": "Tencent Cloud IM"}},{"path": "components/TUIContact/index","style": {"navigationBarTitleText": "Tencent Cloud IM"}},{"path": "components/TUIGroup/index","style": {"navigationBarTitleText": "Tencent Cloud IM"}}]}],"preloadRule": {"TUIKit/components/TUIConversation/index": {"network": "all","packages": ["TUIKit"]}},"globalStyle": {"navigationBarTextStyle": "black","navigationBarTitleText": "uni-app","navigationBarBackgroundColor": "#F8F8F8","backgroundColor": "#F8F8F8"}}
<script lang="ts">// #ifdef APP-PLUS || H5import { TUIChatKit, genTestUserSig } from "./TUIKit";import { vueVersion } from "./TUIKit/adapter-vue";import { TUILogin } from "@tencentcloud/tui-core";// #endif// Mandatory informationconst config = {userID: "test-user1", // User IDSDKAppID: 0, // Your SDKAppIDsecretKey: "", // Your secretKey};uni.$chat_userID = config.userID;uni.$chat_SDKAppID = config.SDKAppID;uni.$chat_secretKey = config.secretKey;// #ifdef APP-PLUS || H5uni.$chat_userSig = genTestUserSig(config).userSig;// Initialization of TUIChatKitTUIChatKit.init();// #endifexport default {onLaunch: function () {// #ifdef APP-PLUS || H5// TUICore loginTUILogin.login({SDKAppID: uni.$chat_SDKAppID,userID: uni.$chat_userID,// A UserSig is a cipher for users to sign in to Instant Messaging - it is essentially the ciphertext resulting from encrypting information such as UserID.// This method is only suitable for running demos locally and debugging features. For more details, please refer to https://cloud.tencent.com/document/product/269/32688userSig: uni.$chat_userSig,// Should you require to transmit imagery, audio, video, files, and other forms of multimedia messages, please set `Setting` as `true`useUploadPlugin: true,// Local audit can identify and handle unsuitable and unsafe content to effectively ensure a pleasant product experience and business security// This feature is an added service, please refer to: https://cloud.tencent.com/document/product/269/79139// If you've purchased the content review service, please enable this feature by setting it to `true`useProfanityFilterPlugin: false,framework: `vue${vueVersion}` // Current development framework in use: vue2 / vue3});// #endif},onShow: function() {console.log('App Show')},onHide: function() {console.log('App Hide')}};</script><style>/*Common CSS for each page*/uni-page-body,html,body,page {width: 100% !important;height: 100% !important;overflow: hidden;}</style>
Note:
The mini program integrates by default in a subpackage. The login must be completed on the TUIKit startup page.
If you do not require the packaging of mini-programs (for instance, building H5 only), you can disregard the configuration content of "Mini Program Split Package Homepage".
Example: The TUIKit sub-package first screen launch page is the TUIConversation page
Step 1: Create a subPackage-init.ts file under the TUIKit/components/TUIConversation directory
import { TUIChatKit, genTestUserSig } from "../../index.ts";import { vueVersion, onMounted } from "../../adapter-vue";import { TUILogin } from "@tencentcloud/tui-core";// Initialization of TUIChatKitTUIChatKit.init();uni.$chat_userSig = genTestUserSig({userID: uni.$chat_userID,SDKAppID: uni.$chat_SDKAppID,secretKey: uni.$chat_secretKey}).userSig;// loginTUILogin.login({SDKAppID: uni.$chat_SDKAppID,userID: uni.$chat_userID,// UserSig is the cipher for users to sign in to Instant Messaging, essentially being the ciphertext obtained from encrypting information such as UserID.// This method is only suitable for running Demo locally and debugging functions. For details, please refer to https://cloud.tencent.com/document/product/269/32688userSig: uni.$chat_userSig,// Should you require to send image, voice, video, file and other rich media messages, please set `Setting` to `true`useUploadPlugin: true,// Local review can successfully identify and handle inappropriate and unsafe content, thereby ensuring the safety and enhancing the user experience of your products// This functionality is a value-added service, please refer to: https://cloud.tencent.com/document/product/269/79139// If you have purchased the content review service, to activate this feature please set it to `true`useProfanityFilterPlugin: false,framework: `vue${vueVersion}` // Current development uses framework vue2 / vue3}).then(() => {uni.showToast({title: "login success"});});
Step 2: Import within TUIKit/components/TUIConversation/index.vue
// #ifdef MP-WEIXINimport "./subPackage-init.ts";// #endif
See the following figure:
3. Configuring the entry points of TUIConversation and TUIContact on the main package homepage of the project
Create an index.vue file under the pages/index folder
<template><div class="index"><p class="index-button" @click="openConversation">Open TUIKit Conversation</p><p class="index-button" @click="openContact">Open TUIKit Contacts</p></div></template><script>export default {methods: {// Open the TUIKit session listopenConversation() {uni.navigateTo({url: "/TUIKit/components/TUIConversation/index",});},// Accessing TUIKit ContactsopenContact() {uni.navigateTo({url: "/TUIKit/components/TUIContact/index",});},},};</script><style lang="scss" scoped>.index {height: 100%;display: flex;flex-direction: column;align-items: center;&-button {width: 180px;padding: 10px 40px;color: #fff;background-color: #006eff;font-size: 16px;margin-top: 65px;border-radius: 30px;text-align: center;}}</style>
Step 4: Gain access to SDKAppID, secretKey, and userID
Within the App.vue file in the root directory of configuration, find
config
object's SDKAppID, secretKey, and userID. The SDKAppID and secretKey can be accessed through the Instant Messaging Console, and the userID can be accessed when creating an account in the Instant Messaging Console.// Mandatory informationconst config = {userID: "test-user1", // Login User IDSDKAppID: 0, // Your SDKAppIDsecretKey: "", // Your secretKey};
access SDKAppID,secretKey
In the Instant Messaging Console under the application management page, you can see the applications you have created. The SDKAppID is in the second column. Then click on the peekKey in the operation options. A dialogue box will appear on the website for the peekKey, and by clicking on the Show Key, the peekKey will be revealed.
Create an account with `userID` as `test-user1`
Click on Account Management on the left side of the console. If you have multiple applications, ensure to switch to your current application. Then, under the current application, click Create new account to create an account with a userID of
test-user1
.Note:
The step of creating an account can be circumvented as TUIKit will auto-generate an account during the sign in process if the configuration's userID does not exist. This only demonstrates how to access the userID.
Step 5. Launch the project
1. Launch the project using HBuilderX, then click on "Run - Run to Mini Program Simulator - WeChat Developer Tools".
2. Should HBuilderX fail to automatically activate the WeChat Developer Toolkit, kindly use the toolkit to manually open the compiled project.
Open the
unpackage/dist/dev/mp-weixin
under the project root directory using the WeChat Developer Tool.3. After opening the project, check the "Do not verify valid domain, web-view (business domain), TLS version, and HTTPS certificate" in "Details-Local Setting" of WeChat Developer Tools.
Step 6. Send your first message
1. Create a User account through the Instant Messaging Console
Navigate to the Account Management page from the left sidebar, and click on New Account to create a regular account with userID:test-user2.
2. Run project and create conversation.
click to open TUIKit conversation , search for user userID:test-user2, and send your first message.
Additional Advanced Features
Audio-Visual Communication TUICallKit Plugin
Note:
The TUICallKit audio/video component is not integrated by default in TUIKit,TUICallKit primarily handles voice and video calls.
Should you need to integrate call functionalities, kindly refer to the following documents for guidelines.
For packaging into APP, refer to: Audio/Video Calling (Client)
For packaging to Miniprogram, please refer to: Video Calls(Miniprogram)
For packaging into HTML5, please refer to the official documentation: Audio and Video Calls (HTML5)
Please stay tuned.
TIMPush Offline Push Plugin
Indication
By default, TUIKit does not integrate the TIMPush offline push plugin.TIMPush is Tencent Cloud's Instant Messaging Push Plugin. Currently, offline push supports Android and iOS platforms, and devices include: Huawei, Xiaomi, OPPO, Vivo, Meizu, and Apple phones.
Should you require the integration of offline push capabilities within your APP, kindly refer to the implementation of uni-app offline push.
Please stay tuned.
Individually integrate TUIChat component
Consider Independent Integration of TUIChat Component as a Solution
FAQs
Exchange and Feedback
Click here to join the IM community, where you'll receive support from experienced engineers to help overcome your challenges.
Reference Documentation
Related to UIKit (vue2 / vue3):
Regarding ChatEngine: