tencent cloud

文档反馈

最后更新时间:2024-06-03 16:50:17

    适用场景

    uniapp 平台,独立集成私信聊天(1V1)或者群聊(Group),如房产中介咨询、电商在线客服、保险远程定损等。
    

    开发环境要求

    HBuilderX (HBuilderX 版本 >= 3.8.4.20230531)或者升级到最新版本
    Vue2 / Vue3
    sass(sass-loader 版本 ≤ 10.1.1)
    node(12.13.0 ≤ node 版本 ≤ 17.0.0, 推荐使用 Node.js 官方 LTS 版本 16.17.0)
    npm(版本请与 node 版本匹配)

    集成 TUIChat

    通过以下步骤发送您的第一条消息。

    步骤1:创建项目 (已有项目可忽略)

    打开 HbuilderX,在菜单栏中选择 “文件-新建-项目”,创建一个名为 chat-example 的 uni-app 项目。
    
    
    

    步骤2:下载 TUIKit

    HBuilderX 不会默认创建 package.json 文件,因此您需要先创建 package.json 文件。请在项目根目录下执行以下命令:
    npm init -y
    下载 TUIKit 并拷贝至源码中:
    macOS 端
    Windows 端
    通过 npm 方式下载 TUIKit 组件:
    npm i @tencentcloud/chat-uikit-uniapp unplugin-vue2-script-setup
    为了方便您后续的拓展,建议您将 TUIKit 组件复制到自己工程的 pages 目录下,请在自己的项目根目录下执行以下命令:
    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 方式下载 TUIKit 组件:
    npm i @tencentcloud/chat-uikit-uniapp unplugin-vue2-script-setup
    为了方便您后续的拓展,建议您将 TUIKit 组件复制到自己工程的 pages 目录下,请在自己的项目根目录下执行以下命令:
    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

    步骤3:引入 TUIKit

    1. 工程配置

    在根目录下创建 vue.config.js (vue3 项目请忽略此步骤)
    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 it
    config.plugins.delete('fork-ts-checker');
    },
    };
    manifest.json 文件的源码视图中开启分包配置
    {
    "mp-weixin": {
    "appid": "",
    "optimization": {
    "subPackages": true
    }
    },
    "h5": {
    "optimization": {
    "treeShaking": {
    "enable": false
    }
    }
    }
    }

    2. 集成 TUIKit

    注意:
    进行集成时,请严格按照以下四个步骤进行集成。如果您希望打包小程序,请不要跳过“小程序分包首页”的配置。
    main.js 文件
    pages.json 文件
    App.vue 文件
    小程序分包首页
    请注意,Vue2环境下要使用Vue.use(VueCompositionAPI) ,防止环境变量isPC等无法使用。
    // 引入主包依赖
    import TencentCloudChat from "@tencentcloud/chat";
    import TUICore from "@tencentcloud/tui-core";
    
    import App from './App';
    
    // #ifndef VUE3
    import 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 VUE3
    import { createSSRApp } from 'vue';
    export function createApp() {
    const app = createSSRApp(App);
    return {
    app,
    };
    }
    // #endif
    {
    "pages": [{
    "path": "pages/index/index" // 您的项目首页
    }],
    "subPackages": [{
    "root": "TUIKit",
    "pages": [
    {
    "path": "components/TUIChat/index",
    "style": {
    "navigationBarTitleText": "腾讯云 IM"
    }
    },
    // 集成 chat 组件,必须配置该路径: 视频播放
    {
    "path": "components/TUIChat/video-play",
    "style": {
    "navigationBarTitleText": "腾讯云 IM"
    }
    },
    {
    "path": "components/TUIChat/web-view",
    "style": {
    "navigationBarTitleText": "腾讯云 IM"
    }
    },
    {
    "path": "components/TUIContact/index",
    "style": {
    "navigationBarTitleText": "腾讯云 IM"
    }
    },
    {
    "path": "components/TUIGroup/index",
    "style": {
    "navigationBarTitleText": "腾讯云 IM"
    }
    }
    ]
    }],
    "preloadRule": {
    "TUIKit/components/TUIChat/index": {
    "network": "all",
    "packages": ["TUIKit"]
    }
    },
    "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "uni-app",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
    }
    }
    <script lang="ts">
    // #ifdef APP-PLUS || H5
    import { TUIChatKit, genTestUserSig } from "./TUIKit";
    import { vueVersion } from "./TUIKit/adapter-vue";
    import { TUILogin } from "@tencentcloud/tui-core";
    // #endif
    // 必填信息
    const config = {
    userID: "test-user1", //User ID
    SDKAppID: 0, // Your SDKAppID
    secretKey: "", // Your secretKey
    };
    uni.$chat_userID = config.userID;
    uni.$chat_SDKAppID = config.SDKAppID;
    uni.$chat_secretKey = config.secretKey;
    
    // #ifdef APP-PLUS || H5
    uni.$chat_userSig = genTestUserSig(config).userSig;
    // TUIChatKit 初始化
    TUIChatKit.init();
    // #endif
    export default {
    onLaunch: function () {
    // #ifdef APP-PLUS || H5
    // TUICore login
    TUILogin.login({
    SDKAppID: uni.$chat_SDKAppID,
    userID: uni.$chat_userID,
    // UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。
    // 该方法仅适合本地跑通 Demo 和功能调试,详情请参见https://www.tencentcloud.com/document/product/269/32688?from_cn_redirect=1
    userSig: uni.$chat_userSig,
    // 如果您需要发送图片、语音、视频、文件等富媒体消息,请设置为 true
    useUploadPlugin: true,
    // 本地审核可识别、处理不安全、不适宜的内容,为您的产品体验和业务安全保驾护航
    // 此功能为增值服务,请参考:https://www.tencentcloud.com/document/product/269/79139?from_cn_redirect=1
    // 如果您已购买内容审核服务,开启此功能请设置为 true
    useProfanityFilterPlugin: false,
    framework: `vue${vueVersion}` // 当前开发使用框架 vue2 / vue3
    });
    // #endif
    },
    onShow: function() {
    console.log('App Show')
    },
    onHide: function() {
    console.log('App Hide')
    }
    };
    </script>
    <style>
    /*每个页面公共css */
    uni-page-body,
    html,
    body,
    page {
    width: 100% !important;
    height: 100% !important;
    overflow: hidden;
    }
    </style>
    示例:小程序分包 TUIKit 首启动页面为 TUIChat 页面 (如果您不需要打包小程序,可忽略此配置页面)。
    请在文件路径: TUIKit/components/TUIChat/index.vue 添加以下内容:
    // #ifdef MP-WEIXIN
    import { TUIChatKit, genTestUserSig } from "../../index.ts";
    import { vueVersion, onMounted } from "../../adapter-vue";
    import { TUILogin } from "@tencentcloud/tui-core";
    import { onLoad } from '@dcloudio/uni-app';
    // #endif
    注意:
    由于条件编译的兼容问题,以下条件编译代码必须写在 const 变量下边。
    // TUIChatKit 初始化
    // 注意: 由于条件编译的兼容问题,以下条件编译代码必须写在 const 变量下边
    // #ifdef MP-WEIXIN
    TUIChatKit.init();
    uni.$chat_userSig = genTestUserSig({
    userID: uni.$chat_userID,
    SDKAppID: uni.$chat_SDKAppID,
    secretKey: uni.$chat_secretKey
    }).userSig;
    
    onLoad((options) => {
    // login
    TUILogin.login({
    SDKAppID: uni.$chat_SDKAppID,
    userID: uni.$chat_userID,
    // UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。
    // 该方法仅适合本地跑通 Demo 和功能调试,详情请参见 https://www.tencentcloud.com/document/product/269/32688?from_cn_redirect=1
    userSig: uni.$chat_userSig,
    // 如果您需要发送图片、语音、视频、文件等富媒体消息,请设置为 true
    useUploadPlugin: true,
    // 本地审核可识别、处理不安全、不适宜的内容,为您的产品体验和业务安全保驾护航
    // 此功能为增值服务,请参考:https://www.tencentcloud.com/document/product/269/79139?from_cn_redirect=1
    // 如果您已购买内容审核服务,开启此功能请设置为 true
    useProfanityFilterPlugin: false,
    framework: `vue${vueVersion}` // 当前开发使用框架 vue2 / vue3
    }).then(() => {
    uni.showToast({
    title: "login success"
    });
    const conversationID = options.conversationID;
    TUIConversationService.switchConversation(conversationID);
    });
    });
    // #endif
    如图所示:
    

    步骤4:获取 SDKAppID、secretKey、userID

    配置根目录下 App.vue 文件中 config 对象的 SDKAppID、secretKey 以及 userID。其中 SDKAppID 、secretKey 可通过 即时通信 IM 控制台获取,userID 可在 即时通信 IM 控制台 中创建账户时获取。
    // 必填信息
    const config = {
    userID: "test-user1", // Login User ID
    SDKAppID: 0, // Your SDKAppID
    secretKey: "", // Your secretKey
    };
    获取 SDKAppID、secretKey
    即时通信 IM 控制台中的应用管理页面下,可以看到您创建的应用,第二列即是 SDKAppID,然后点击操作中的查看密钥。网站会弹出查看密钥的对话框,然后点击显示密钥,即可查看密钥。
    创建 userID 为 test-user1 的账户
    说明:
    创建账户的步骤可以跳过,因为 TUIKit 进行登录时,若配置的 userID 不存在,会自动创建账户,此处仅展示如何获取 userID。
    单击控制台左侧的账号管理,如果您有多个应用,请注意切换至当前应用,然后在当前应用下单击新建账号,创建一个 userID 为 test-user1 的账号。
    
    
    

    步骤5:在项目主包首页中配置单聊和群聊的入口

    在 pages/index 文件夹下创建 index.vue 文件,填写 userID/groupID:
    说明:
    conversationID:会话 ID。会话ID组成方式:
    C2C${userID}(单聊)
    GROUP${groupID}(群聊)
    关于群聊:
    通过调用 createGroup 创建群组后获取对应的 groupID
    如果是直播群, 需要通过调用 API joinGroup加入群,才可以进行聊天。
    进入聊天
    通过调用 switchConversation,进入聊天页面。
    <template>
    <div class="TUI-chat">
    <p class="TUI-chat-button" @click="openChat">打开 1v1 聊天</p>
    <p class="TUI-chat-button" @click="openGroupChat">打开群聊</p>
    </div>
    </template>
    <script>
    import { TUIConversationService } from "@tencentcloud/chat-uikit-engine";
    export default {
    components: {},
    data() {
    return {
    userID: "test-user2", // 请填写对端 userID 参考步骤6
    groupID: "", // 通过调用 API createGroup 可获取 groupID,具体可参考:https://web.sdk.qcloud.com/im/doc/chat-engine/ITUIGroupService.html#createGroup
    };
    },
    methods: {
    // 打开 1v1 聊天
    openChat() {
    // 切换会话进入聊天
    const conversationID = `C2C${this.userID}`;
    // #ifdef APP-PLUS || H5
    TUIConversationService.switchConversation(conversationID);
    // #endif
    uni.navigateTo({
    url: `/TUIKit/components/TUIChat/index?conversationID=${conversationID}`,
    });
    },
    // 打开群聊
    openGroupChat() {
    const conversationID = `GROUP${this.groupID}`;
    // #ifdef APP-PLUS || H5
    TUIConversationService.switchConversation(conversationID);
    // #endif
    uni.navigateTo({
    url: `/TUIKit/components/TUIChat/index?conversationID=${conversationID}`,
    });
    },
    },
    };
    </script>
    <style lang="scss" scoped>
    .TUI-chat {
    display: flex;
    flex-direction: column;
    align-items: center;
    height: 100%;
    &-button {
    width: 180px;
    padding: 10px 40px;
    background-color: #006eff;
    color: #fff;
    font-size: 16px;
    margin-top: 65px;
    border-radius: 30px;
    text-align: center;
    }
    }
    </style>

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

    1. 通过即时通信 IM 控制台创建一个 User 账号
    从控制台的左侧边栏进入账号管理页面,单击新建账号并创建一个普通账号,userID:test-user2。
    
    
    
    2. 使用 HBuilderX 启动该项目,单击运行 > 运行到小程序模拟器 > 微信开发者工具
    
    
    
    3. 如果 HBuilderX 没有自动拉起微信开发者工具,请使用微信开发者工具手动打开编译后的项目。
    使用微信开发者工具打开项目根目录下的 unpackage/dist/dev/mp-weixin 即可。
    4. 打开项目后,在微信开发者工具的详情 > 本地设置中勾选不校验合法域名、web-view(业务域名)、TLS版本以及 HTTPS 证书
    5. 发起会话
    单击打开 1v1 聊天,发送您的第一条消息。

    更多高级特性

    音视频通话 TUICallKit 插件

    说明:
    TUIKit 中默认没有集成 TUICallKit 音视频组件,TUICallKit 主要负责语音、视频通话。
    如果您需要集成通话功能,可参考以下文档实现。
    打包到 APP 请参考: 音视频通话(客户端)
    打包到小程序请参考:音视频通话(小程序)
    打包到 H5 请参考官:音视频通话(H5)
    敬请期待。

    TIMPush 离线推送插件

    说明
    TUIKit 中默认没有集成 TIMPush 离线推送插件。TIMPush 是腾讯云即时通信 IM Push 插件。目前离线推送支持 Android 和 iOS 平台,设备有:华为、小米、OPPO、vivo、魅族 和 苹果手机。
    如果您需要在 App 中集成离线推送能力,请参见 uni-app 离线推送 实现。
    敬请期待。

    常见问题

    1. 独立集成场景下,如何清除会话未读数?

    答:在执行“步骤2 -> 集成 TUIKit 组件 -> 小程序分包首页”这一步时,TUIChat 在 onLoad 事件里调用了 TUIConversationService.switchConversation() 方法,该方法会主动清除当前会话的未读数,因此不需要手动清除会话未读数。
    
    更多问题请参见 Uniapp FAQ

    技术咨询

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

    参考文档

    UIKit (vue2 / vue3)相关:
    ChatEngine 相关:
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持