小程序

最近更新时间:2024-09-09 16:10:01

我的收藏

TUIKit 介绍

TUIKit 是基于腾讯云 IM SDK 的一款 UI 组件库,它提供了一些通用的 UI 组件,包含会话、聊天、群组、音视频通话等功能。 基于 UI 组件您可以像搭积木一样快速搭建起自己的业务逻辑。 TUIKit 中的组件在实现 UI 功能的同时,会调用 IM SDK 相应的接口实现 IM 相关逻辑和数据的处理,因而开发者在使用 TUIKit 时只需关注自身业务或个性化扩展即可。

TUIKit 主要功能介绍

TUIKit 主要分为 TUIConversation、TUIChat、TUICallKit、和TUIGroup 几个 UI 子组件,每个 UI 组件负责展示不同的内容。 界面效果如下图所示:



在线客服界面效果如下图所示:



注意
1. 如果您在集成 TUIKit 之后还需要客服功能,请参见客服场景
2. 如果您在集成 TUIKit 之后还需要支持单人/多人音视频通话功能,详情请参见 使用音视频通话

开发环境要求

微信开发者工具
JavaScript
node(node.js ≥ 16.0.0)
npm(版本请与 node 版本匹配)

TUIKit 源码集成

说明:
@tencentcloud/chat-uikit-wechat 使用 WebView 渲染,暂不支持 Skyline 渲染。

步骤1:创建项目

1. 创建项目,在微信开发者工具上创建一个不使用模板的小程序项目,选择。如图所示:

2. 配置渲染模式,在 app.json 中设置 rendererwebview。如图所示:
{
"pages": [
"pages/index/index"
],
"window": {
"navigationBarTextStyle": "black",
"navigationStyle": "custom"
},
"style": "v2",
"renderer": "webview"
}


步骤2:下载 TUIKit 组件

1. 创建 package.josn,微信开发者工具创建的小程序项目默认没有 package.json,因此您需要先创建 package.json 文件,如图所示:
npm init -y

2. 通过 npm 方式下载 TUIKit 组件, 并复制到自己的小程序目录下,目录结构如图所示:
macOS 端
Windows 端
npm i @tencentcloud/chat-uikit-wechat
mkdir -p ./TUIKit && cp -r node_modules/@tencentcloud/chat-uikit-wechat/ ./TUIKit
npm i @tencentcloud/chat-uikit-wechat
xcopy node_modules\\@tencentcloud\\chat-uikit-wechat .\\TUIKit /i /e

3. 构建 npm:单击工具 > 构建 npm,构建成功会新增 miniprogram_npm 文件夹,如图所示:


步骤3:引入 TUIKit 组件

说明:
小程序分包有如下好处:
规避所有逻辑代码放主包,导致主包文件体积超限问题;
支持按需载入,降低小程序载入耗时和页面渲染耗时;
支持更加复杂的功能。
为尊重表情设计版权,IM Demo/TUIKit 工程中不包含大表情元素切图,正式上线商用前请您替换为自己设计或拥有版权的其他表情包。下图所示默认的小黄脸表情包版权归腾讯云所有,可有偿授权使用,如需获得授权可 提交工单 联系我们。



分包引入(推荐)
主包引入 (适用于业务逻辑简单的小程序)
1. 在自己项目里创建分包,本文以 TUI-CustomerService 为例。和 pages 同级创建 TUI-CustomerService 文件夹,并在文件夹内部创建 pages 文件夹并且其下创建 index 页面,将 TUIKit 移动到 TUI-CustomerService 目录下,并在 app.json 中注册分包。如图所示:
{
"pages": [
"pages/index/index"
],
"subPackages": [
{
"root": "TUI-CustomerService",
"name": "TUI-CustomerService",
"pages": [
"pages/index"
],
"independent": false
}
],
"window": {
"backgroundTextStyle": "light",
"navigationBarBackgroundColor": "#fff",
"navigationBarTitleText": "Weixin",
"navigationBarTextStyle": "black"
},
"style": "v2",
"renderer": "webview",
"sitemapLocation": "sitemap.json"
}

2. 将 TUIKit 文件夹下的 debug 文件夹复制到主包,并在 app.js 初始化 chat 和设置 TUIKit 参数,如图所示:
import TencentCloudChat from '@tencentcloud/chat';
import TIMUploadPlugin from 'tim-upload-plugin';
import TIMProfanityFilterPlugin from 'tim-profanity-filter-plugin';
import { genTestUserSig } from './debug/GenerateTestUserSig';
App({
onLaunch: function () {
wx.$TUIKit = TencentCloudChat.create({
SDKAppID: this.globalData.config.SDKAPPID,
});
const userSig = genTestUserSig(this.globalData.config).userSig
wx.$chat_SDKAppID = this.globalData.config.SDKAPPID;
wx.TencentCloudChat = TencentCloudChat;
wx.$chat_userID = this.globalData.config.userID;
wx.$chat_userSig = userSig;
wx.$TUIKit.registerPlugin({ 'tim-upload-plugin': TIMUploadPlugin });
wx.$TUIKit.registerPlugin({ 'tim-profanity-filter-plugin': TIMProfanityFilterPlugin });
wx.$TUIKit.login({
userID: this.globalData.config.userID,
userSig
});
// 监听系统级事件
wx.$TUIKit.on(wx.TencentCloudChat.EVENT.SDK_READY, this.onSDKReady,this);
},
onUnload() {
wx.$TUIKit.off(wx.TencentCloudChat.EVENT.SDK_READY, this.onSDKReady,this);
},
globalData: {
config: {
userID: '', // User ID
SECRETKEY: '', // Your secretKey
SDKAPPID: 0, // Your SDKAppID
EXPIRETIME: 604800,
},
},
onSDKReady(event) {
// 监听到此事件后可调用 SDK 发送消息等 API,使用 SDK 的各项功能。
}
});

3. 在分包内引用 TUIKit组件,为此需要分别修改分包内部 index.wxml 、index.js 、index.json 文件。
json 文件
wxml 文件
js 文件
在 TUI-CustomerService/pages/index/index.json 中引入 TUIKit 组件,如图所示:
{
"usingComponents": {
"TUIKit": "../TUIKit/index"
},
"navigationStyle": "custom"
}

在 TUI-CustomerService/pages/index/index.wxml 中使用 TUIKit 组件,如图所示:
<view>
<TUIKit config="{{config}}" id="TUIKit"></TUIKit>
</view>
config 的参数如下表所示:
参数
类型
是否必填
含义
userID
String
当前用户的 ID,字符串类型,只允许包含英文字母(a-z 和 A-Z)、数字(0-9)、连词符(-)和下划线(_)
SDKAPPID
Number
云通信应用的 SDKAppID
SECRETKEY
String
密钥信息,详情可参见 步骤4
EXPIRETIME
Number
userSig 过期时间

在 TUI-CustomerService/pages/index/index.js 中启用 TUIKit 组件,如图所示:
Page({

// 其他代码

onLoad() {
const TUIKit = this.selectComponent('#TUIKit');
TUIKit.init();
},
});

4. 按需载入分包,您需要修改主包 pages 下的 index.wxml 、index.js。
wxml 文件
js 文件
在 pages/index/index.wxml 中增加载入分包的入口,如图所示:
<view class="container" bindtap="handleJump">
载入腾讯云 IM 分包
</view>

在 pages/index/index.js 中增加载入分包的入口方法,如图所示:
Page({
handleJump() {
wx.navigateTo({
url: '../../TUI-CustomerService/pages/index',
})
}
})

在 page 页面引用 TUIKit 组件,为此您需要分别修改 index.wxml 、index.js 和 index.json。
json 文件
wxml 文件
js 文件
在 pages/index/index.json 中引入 TUIKit 组件,如图所示:
{
"usingComponents": {
"TUIKit": "../../TUIKit/index"
},
"navigationStyle": "custom"
}



在 pages/index/index.wxml 中使用 TUIKit 组件,如图所示:
<view>
<TUIKit config="{{config}}" id="TUIKit"></TUIKit>
</view>
config 的参数如下表所示:
参数
类型
是否必填
含义
userID
String
当前用户的 ID,字符串类型,只允许包含英文字母(a-z 和 A-Z)、数字(0-9)、连词符(-)和下划线(_)
SDKAPPID
Number
云通信应用的 SDKAppID
SECRETKEY
String
密钥信息,详情可参考 步骤4
EXPIRETIME
Number
userSig 过期时间



在 pages/index/index.js 中配置 TUIKit 参数、初始化 Chat、启用 TUIKit,如图所示:
import TencentCloudChat from '@tencentcloud/chat';
import TIMUploadPlugin from 'tim-upload-plugin';
import TIMProfanityFilterPlugin from 'tim-profanity-filter-plugin';
import { genTestUserSig } from '../../TUIKit/debug/GenerateTestUserSig';

Page({
data: {
config: {
userID: '', //User ID
SDKAPPID: 0, // Your SDKAppID
SECRETKEY: '', // Your secretKey
EXPIRETIME: 604800,
}
},

onLoad() {
const userSig = genTestUserSig(this.data.config).userSig
wx.$TUIKit = TencentCloudChat.create({
SDKAppID: this.data.config.SDKAPPID
})
wx.$chat_SDKAppID = this.data.config.SDKAPPID;
wx.$chat_userID = this.data.config.userID;
wx.$chat_userSig = userSig;
wx.TencentCloudChat = TencentCloudChat;
wx.$TUIKit.registerPlugin({ 'tim-upload-plugin': TIMUploadPlugin });
wx.$TUIKit.registerPlugin({ 'tim-profanity-filter-plugin': TIMProfanityFilterPlugin });
wx.$TUIKit.login({
userID: this.data.config.userID,
userSig
});
wx.setStorage({
key: 'currentUserID',
data: [],
});
wx.$TUIKit.on(wx.TencentCloudChat.EVENT.SDK_READY, this.onSDKReady,this);
},
onUnload() {
wx.$TUIKit.off(wx.TencentCloudChat.EVENT.SDK_READY, this.onSDKReady,this);
},
onSDKReady() {
const TUIKit = this.selectComponent('#TUIKit');
TUIKit.init();
}
});





步骤4: 获取 SDKAppID 、SECRETKEY 与 userID

通过 即时通信 IM 控制台 > 应用管理获取 SDKAPPID、SECRETKEY ,并设置 步骤3 示例代码中的 SDKAPPID、SECRETKEY。


通过 即时通信 IM 控制台 > 账号管理创建账号并获取 userID,并设置 步骤3 示例代码中的 userID。


步骤5:编译小程序

1. 本地设置里面勾选上“不校验合法域名、web-view (业务域名)、 TLS 版本以及 HTTPS 证书”。
2. 单击清缓存 > 全部清除。避免开发者工具的缓存造成渲染异常。
3. 单击编译
具体实现如图所示:


步骤6:发送您的第一条消息


注意
1. 如果您在集成 TUIKit 之后还需要客服功能,请参见客服场景
2. 如果您在集成 TUIKit 之后还需要支持单人/多人音视频通话功能,请参见 使用音视频通话

更多高级特性(强烈推荐)

注意:
@tencentcloud/chat-uikit-wechat ≥ 2.0.2 默认支持, 只需要进入 控制台 > 插件市场 > 客服插件 ,单击免费试用购买插件即可使用在线客服功能。



在消息发送、资料修改场景中,很有可能会扩散不合适的内容,特别是与敏感事件/人物相关、黄色不良内容等令人反感的内容,不仅严重损害了用户们的身心健康,更很有可能违法并导致业务被监管部门查封。
即时通信 IM 支持内容审核(反垃圾信息)功能,可针对不安全、不适宜的内容进行自动识别、处理,为您的产品体验和业务安全保驾护航。可以通过 云端审核 方式来实现。

常见问题

1. 什么是 UserSig?

UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。

2. 如何生成 UserSig?

UserSig 签发方式是将 UserSig 的计算代码集成到您的服务端,并提供面向项目的接口,在需要 UserSig 时由您的项目向业务服务器发起请求获取动态 UserSig。更多详情请参见 服务端生成 UserSig
注意
本文示例代码采用的获取 UserSig 的方案是在客户端代码中配置 SECRETKEY,该方法中 SECRETKEY 很容易被反编译逆向破解,一旦您的密钥泄露,攻击者就可以盗用您的腾讯云流量,因此该方法仅适合本地跑通功能调试。 正确的 UserSig 签发方式请参见上文。

3. 小程序如果需要上线或者部署正式环境怎么办?

请在 微信公众平台 > 开发 > 开发管理 > 开发设置 > 服务器域名 中进行域名配置,域名配置方法请参见: 小程序 socket 合法域名

技术咨询

点此进入 IM 社群,享有专业工程师的支持,解决您的难题。