Web(Vue)

적용 시나리오

Web & H5 플랫폼은 부동산 중개 상담, 전자상거래 온라인 고객 서비스, 원격 보험금 청구 평가 등 시나리오에서 개인 메시징(1V1) 또는 그룹 채팅(Group)을 별도로 통합합니다.


개발 환경 요구사항

Vue (Vue2 & Vue3 지원됩니다. 아래에서 액세스할 때 매칭되는 Vue 액세스 가이드를 선택하여 액세스하십시오.)
TypeScript (js 프로젝트인 경우, js 프로젝트가 TUIKit 컴포넌트에 액세스하는 방법으로 이동하셔서 ts 프로그레시브 지원을 구성하십시오.)
sass(sass-loader 버전 ≤ 10.1.1)
node(node.js ≥ 16.0.0)
npm(node 버전과 매칭되는 버전)

TUIKit 소스 코드 통합( Web & H5 )

단계 1: 프로젝트 생성

TUIKit는 webpack 또는 vite를 사용하여 프로젝트를 생성하고 Vue3 / Vue2 + TypeScript + sass를 구성하는 것을 지원합니다. 다음은 몇 가지 프로젝트 구축 예시입니다.
vue-cli
vite
주의:
반드시 @vue/cli 5.0.0 이상 버전이어야 합니다. 아래 예시 코드를 사용하여 당신의 @vue/cli 버전을 v5.0.8로 업그레이드할 수 있습니다.
vue-cli 방식을 통해 프로젝트를 생성하고 Vue2 / Vue3 + TypeScript + sass를 구성합니다. vue-cli를 아직 설치하지 않았거나 vue-cli 버전이 5.0.0보다 낮으면 terminal 또는 cmd에서 아래 방식으로 설치할 수 있습니다.
npm install -g @vue/cli@5.0.8 sass sass-loader@10.1.1
vue-cli를 통해 프로젝트를 생성하고 아래 그림에서 선택한 구성 항목을 선택합니다.
vue create chat-example
반드시 아래 구성에 따라 선택해야 합니다.

생성 완료 후 프로젝트가 위치한 디렉터리로 전환합니다.
cd chat-example
vue2 프로젝트인 경우, 사용 중인 Vue 버전에 따라 다음과 같이 해당 환경을 구성합니다. vue3 프로젝트인 경우 무시하십시오.
vue2.7
vue2.6 및 이하
npm i vue@2.7.9 vue-template-compiler@2.7.9
npm i @vue/composition-api unplugin-vue2-script-setup vue@2.6.14 vue-template-compiler@2.6.14
주의:
Vite는 Node.js** 18+, 20+ 버전이 필요합니다. 패킷 매니저에서 경고가 뜨는 경우 Node 버전을 업그레이드하십시오. 자세한 내용은 vite 공식 웹사이트를 참고하십시오.
vite 방식으로 프로젝트를 생성하는 경우 아래 그램의 옵션에 따라 Vue + TypeScript 를 구성합니다.
npm create vite@latest

그 다음 프로젝트 디렉터리로 전환합니다. 프로젝트 종속성 설치:
cd chat-example
npm install
TUIKit 설치에 필요한 sass 환경 종속성:
npm i -D sass sass-loader

단계 2: TUIKit 컴포넌트 다운로드

npm 방식으로 TUIKit 컴포넌트를 다운로드하며, 후속 확장을 위해 TUIKit 컴포넌트를 당신 프로젝트의 src 디렉터리에 복사하시는 것을 권장합니다.
macOS 측
Windows 측
npm i @tencentcloud/chat-uikit-vue
mkdir -p ./src/TUIKit && rsync -av --exclude={'node_modules','package.json','excluded-list.txt'} ./node_modules/@tencentcloud/chat-uikit-vue/ ./src/TUIKit
npm i @tencentcloud/chat-uikit-vue
xcopy .\node_modules\@tencentcloud\chat-uikit-vue .\src\TUIKit /i /e /exclude:.\node_modules\@tencentcloud\chat-uikit-vue\excluded-list.txt
성공 후 디렉터리 구조는 다음과 같습니다.


단계 3: TUIKit 컴포넌트 가져오기

main.ts / main.js에서 TUIKit를 가져오고 Vue 프로젝트 인스턴스에 등록합니다.
Vue3 버전
Vue2 버전
import { createApp } from 'vue';
import App from './App.vue';
import { TUIComponents, TUIChatKit, genTestUserSig } from "./TUIKit";
import { TUILogin } from "@tencentcloud/tui-core"; const app = createApp(App);

const SDKAppID = 0; // Your SDKAppID
const secretKey = ""; //Your secretKey
const userID = ""; // User ID

// TUIChatKit add TUIComponents
TUIChatKit.components(TUIComponents, app);
// TUIChatKit init
TUIChatKit.init();
// TUICore login
TUILogin.login({
SDKAppID,
userID,
// UserSig is a password used to log in to IM. It is the ciphertext obtained after data such as UserID is encrypted.
// this method is only suitable for locally running a demo project and feature debugging. https://cloud.tencent.com/document/product/269/32688
userSig: genTestUserSig({
SDKAppID,
secretKey,
userID,
}).userSig,
useUploadPlugin: true,
useProfanityFilterPlugin: false,
framework: "vue3",
});

app.mount("#app");
export { SDKAppID, secretKey };
import Vue from "vue";
import App from "./App.vue";
import { TUIComponents, TUIChatKit, genTestUserSig } from "./TUIKit";
import { TUILogin } from "@tencentcloud/tui-core";

const SDKAppID = 0; // Your SDKAppID
const secretKey = ""; //Your secretKey
const userID = ""; // User ID

// TUIChatKit add TUIComponents
TUIChatKit.components(TUIComponents, Vue);
// TUIChatKit init
TUIChatKit.init();
// TUICore login
TUILogin.login({
SDKAppID,
userID,
// UserSig is a password used to log in to IM. It is the ciphertext obtained after data such as UserID is encrypted.
// this method is only suitable for locally running a demo project and feature debugging. https://cloud.tencent.com/document/product/269/32688
userSig: genTestUserSig({
SDKAppID,
secretKey,
userID,
}).userSig,
useUploadPlugin: true,
useProfanityFilterPlugin: false,
framework: "vue2",
});
Vue.config.productionTip = false;
new Vue({
render: (h) => h(App),
}).$mount("#app");
export { SDKAppID, secretKey };

단계 4: SDKAppID, secretKey와 userID 획득

main.ts / main.js 파일 예시 코드 중의 관련 매개변수 SDKAppID, secretKey 및 userID 설정:
SDKAppID 및 secretKey 등 정보는 Chat 콘솔을 통해 획득할 수 있습니다.


userID 정보의 경우, Chat 콘솔 > 계정 관리를 클릭하여 타겟 애플리케이션이 위치한 계정으로 전환하면 계정을 생성하고 userID를 획득할 수 있습니다.


단계 5: userID / groupID를 입력하고 대화를 열어 채팅하십시오.

설명:
conversationID: 대화 ID. 대화 ID 구성 방식:
C2C${userID}(1대1 채팅)
GROUP${groupID}(그룹 채팅)
그룹 채팅에 관하여:
API [createGroup](https://web.sdk.qcloud.com/im/doc/chat-engine/ITUIGroupService.html#createGroup !7a98f97b561db02dacd13003fe30cc3d)을 호출함으로써 groupID를 획득할 수 있습니다.
라이브 방송 그룹인 경우, API joinGroup을 호출하여 그룹에 가입해야만 채팅할 수 있습니다.
채팅 들어가기
API switchConversation을 호출함으로써 conversationID를 입력하여 채팅 페이지로 들어갑니다.
Vue3 버전
Vue2.7 버전
Vue2.6 및 이하 버전
표시할 페이지에 TUIKit 컴포넌트를 가져오면 사용할 수 있습니다. 예: App.vue 페이지에서 TUIChat, TUICallKit를 사용하여 채팅 인터페이스를 빠르게 구축할 수 있습니다(아래 예시 코드는 동시에 Web 측과 H5 측에서 지원됩니다).
<template>
<div :class="['TUIKit', isH5 && 'TUIKit-h5']">
<div class="TUIKit-main-container">
<div
v-show="!isH5 || !currentConversationID"
:class="['navbar', isH5 && 'navbar-h5']"
>
<div class="navbar-button" @click="openChat">Open OneToOne Chat</div>
<div class="navbar-button" @click="openGroupChat">Open Group Chat</div>
</div>
<TUIChat v-show="!isH5 || currentConversationID">
<h1>Let's chat!</h1>
</TUIChat>
<TUICallKit
class="callkit-container"
:allowedMinimized="true"
:allowedFullScreen="false"
/>
</div>
</div>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { TUIStore, StoreName, TUIConversationService } from "@tencentcloud/chat-uikit-engine";
import { TUICallKit } from "@tencentcloud/call-uikit-vue";
import { TUIChat } from "./TUIKit";
import { isH5 } from "./TUIKit/utils/env";
const currentConversationID = ref<string>("");
const userID = "";// Please enter the userID you want to chat
const groupID = "";// Please enter the groupID you want to chat
TUIStore.watch(StoreName.CONV, {
currentConversationID: (id: string) => {
currentConversationID.value = id;
},
});
function openChat() {
TUIConversationService.switchConversation(`C2C${userID}`);
}
function openGroupChat() {
TUIConversationService.switchConversation(`GROUP${groupID}`);
}
</script>
<style scoped lang="scss">
@import "./TUIKit/assets/styles/common.scss";
@import "./TUIKit/assets/styles/sample.scss";
.navbar {
box-sizing: border-box;
min-width: 285px;
flex: 0 0 24%;
border-right: 1px solid #f4f5f9;
padding: 20px;
.navbar-button {
padding: 10px 40px;
background-color: #006eff;
color: #ffffff;
font-size: 16px;
margin-top: 65px;
border-radius: 30px;
text-align: center;
cursor: pointer;
}
}
.navbar-h5 {
flex: 1;
border-right: 1px solid #f4f5f9;
.navbar-button {
cursor: none;
}
}
.chat {
flex: 1;
}
</style>
표시할 페이지에 TUIKit 컴포넌트를 가져오면 사용할 수 있습니다. 예: App.vue 페이지에서 TUIChat, TUICallKit를 사용하여 채팅 인터페이스를 빠르게 구축할 수 있습니다(아래 예시 코드는 동시에 Web 측과 H5 측에서 지원됩니다).
<template>
<div :class="['TUIKit', isH5 && 'TUIKit-h5']">
<div class="TUIKit-main-container">
<div
v-show="!isH5 || !currentConversationID"
:class="['navbar', isH5 && 'navbar-h5']"
>
<div class="navbar-button" @click="openChat">Open OneToOne Chat</div>
<div class="navbar-button" @click="openGroupChat">Open Group Chat</div>
</div>
<TUIChat v-show="!isH5 || currentConversationID">
<h1>Let's chat!</h1>
</TUIChat>
<TUICallKit
class="callkit-container"
:allowedMinimized="true"
:allowedFullScreen="false"
/>
</div>
</div>
</template>
<script lang="ts">
import Vue from "vue";
import { TUIStore, StoreName, TUIConversationService } from "@tencentcloud/chat-uikit-engine";
import { TUICallKit } from "@tencentcloud/call-uikit-vue2";
import { TUIChat } from "./TUIKit";
import { isH5 } from "./TUIKit/utils/env";
export default Vue.extend({
name: "App",
components: {
TUIChat,
TUICallKit,
},
data() {
return {
isH5: isH5,
currentConversationID: "",
currentNavbar: "conversation",
userID: "", // Please enter the userID you want to chat
groupID: "", // Please enter the groupID you want to chat
};
},
methods: {
openChat() {
TUIConversationService.switchConversation(`C2C${this.userID}`);
},
openGroupChat() {
TUIConversationService.switchConversation(`GROUP${this.groupID}`);
},
},
mounted: function () {
TUIStore.watch(StoreName.CONV, {
currentConversationID: (id: string) => {
this.currentConversationID = id;
},
});
},
});
</script>
<style scoped lang="scss">
@import "./TUIKit/assets/styles/common.scss";
@import "./TUIKit/assets/styles/sample.scss";
.navbar {
box-sizing: border-box;
min-width: 285px;
flex: 0 0 24%;
border-right: 1px solid #f4f5f9;
padding: 20px;
.navbar-button {
padding: 10px 40px;
background-color: #006eff;
color: #ffffff;
font-size: 16px;
margin-top: 65px;
border-radius: 30px;
text-align: center;
cursor: pointer;
}
}
.navbar-h5 {
flex: 1;
border-right: 1px solid #f4f5f9;
.navbar-button {
cursor: none;
}
}
.chat {
flex: 1;
}
</style>
1. composition-api 및 script setup을 지원하는 관련 종속성, 및 vue2.6 관련 종속성을 설치합니다.
npm i @vue/composition-api unplugin-vue2-script-setup vue@2.6.14 vue-template-compiler@2.6.14
2. main.ts에서 VueCompositionAPI 가져오기:
import VueCompositionAPI from "@vue/composition-api";
Vue.use(VueCompositionAPI);
3. vue.config.js에 추가하며, 해당 파일이 없으면 새로 생성하십시오.
const ScriptSetup = require("unplugin-vue2-script-setup/webpack").default;
module.exports = {
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. src/TUIKit/adapter-vue.ts 파일 마지막에 내보내기 소스를 교체합니다.
// 초기 작성법
export * from "vue";
//
export * from "@vue/composition-api"로 교체;
5. 표시할 페이지에 TUIKit 컴포넌트를 가져오면 사용할 수 있습니다. 예: App.vue 페이지에서 TUIChat, TUICallKit를 사용하여 채팅 인터페이스를 빠르게 구축할 수 있습니다(아래 예시 코드는 동시에 Web 측과 H5 측에서 지원됩니다).
<template>
<div :class="['TUIKit', isH5 && 'TUIKit-h5']">
<div class="TUIKit-main-container">
<div
v-show="!isH5 || !currentConversationID"
:class="['navbar', isH5 && 'navbar-h5']"
>
<div class="navbar-button" @click="openChat">Open OneToOne Chat</div>
<div class="navbar-button" @click="openGroupChat">Open Group Chat</div>
</div>
<TUIChat v-show="!isH5 || currentConversationID">
<h1>Let's chat!</h1>
</TUIChat>
<TUICallKit
class="callkit-container"
:allowedMinimized="true"
:allowedFullScreen="false"
/>
</div>
</div>
</template>
<script lang="ts">
import Vue from "vue";
import { TUIStore, StoreName, TUIConversationService } from "@tencentcloud/chat-uikit-engine";
import { TUICallKit } from "@tencentcloud/call-uikit-vue2.6";
import { TUIChat } from "./TUIKit";
import { isH5 } from "./TUIKit/utils/env";
export default Vue.extend({
name: "App",
components: {
TUIChat,
TUICallKit,
},
data() {
return {
isH5: isH5,
currentConversationID: "",
currentNavbar: "conversation",
userID: "", // Please enter the userID you want to chat
groupID: "", // Please enter the groupID you want to chat
};
},
methods: {
openChat() {
TUIConversationService.switchConversation(`C2C${this.userID}`);
},
openGroupChat() {
TUIConversationService.switchConversation(`GROUP${this.groupID}`);
},
},
mounted: function () {
TUIStore.watch(StoreName.CONV, {
currentConversationID: (id: string) => {
this.currentConversationID = id;
},
});
},
});
</script>
<style scoped lang="scss">
@import "./TUIKit/assets/styles/common.scss";
@import "./TUIKit/assets/styles/sample.scss";
.navbar {
box-sizing: border-box;
min-width: 285px;
flex: 0 0 24%;
border-right: 1px solid #f4f5f9;
padding: 20px;
.navbar-button {
padding: 10px 40px;
background-color: #006eff;
color: #ffffff;
font-size: 16px;
margin-top: 65px;
border-radius: 30px;
text-align: center;
cursor: pointer;
}
}
.navbar-h5 {
flex: 1;
border-right: 1px solid #f4f5f9;
.navbar-button {
cursor: none;
}
}
.chat {
flex: 1;
}
</style>

단계 6: 프로젝트 시작

아래 명령을 실행하여 프로젝트를 시작합니다.
vue-cli
vite
npm run serve
npm run dev

자주 받는 질문들

제품 서비스 관련 문제

1. 오디오/비디오 통화 능력 미활성화? 오디오/비디오 전화 걸기 실패?

오디오/비디오 통화 > 자주 받는 질문들을 클릭하여 솔루션을 확인하십시오.

2. UserSig란 무엇입니까? UserSig을 어떻게 생성합니까?

UserSig은 사용자 Chat에 로그인하기 위한 비밀번호로 본질적으로는 UserID 등 정보에 대한 암호화를 통해 얻은 암호문입니다.
UserSig 발급 방식은 UserSig의 컴퓨팅 코드를 당신의 서버 측에 통합하고 프로젝트 지향의 인터페이스를 제공하며, UserSig이 필요할 때 프로젝트에서 업무 서버로 요청을 개시하여 동적 UserSig을 획득하는 것입니다. 자세한 내용은 서버 측 UserSig 생성을 참고하시기 바랍니다.
주의:
여기서 예시된 코드는 클라이언트 코드에 SECRETKEY를 구성하여 UserSig을 획득하는 솔루션을 채택하였으며, 이 솔루션에서 SECRETKEY는 역컴파일에 의해 쉽게 해독되며, 암호키가 유출되면 공격자가 당신의 Tencent Cloud 트래픽을 도용할 수 있으므로, 이 방법은 로컬 실행 및 기능 디버깅에만 적용됩니다. 정확한 UserSig 발급 방식은 위의 내용을 참고하십시오.

액세스 오류 관련 문제

1. 실행 시 오류: "TypeError: Cannot read properties of undefined (reading "getFriendList")"

상기 단계에 따라 액세스한 후 실행 시 아래와 같은 오류가 발생하면, TUIKit의 종속성 유일성을 보장하여 TUIKit 다중 종속성으로 인한 문제를 피하기 위해 부디 TUIKit 디렉터리의 node_modules 디렉터리를 삭제하시기 바랍니다.
259937368-f7c85dfe-b4bd-4c73-88d9-3a9f0d7797f2.png (1186×550)


2. js 프로젝트는 TUIKit 컴포넌트에 어떻게 액세스합니까?

TUIKit는 ts 환경에서만 실행 가능하며, 당신의 프로젝트 중에 있는 js 코드와 TUIKit 중의 ts 코드가 공존할 수 있도록 프로그레시브를 통해 typescript를 구성할 수 있습니다.
vue-cli
vite
vue-cli 비계를 통해 생성한 프로젝트 루트 디렉터리에서 다음을 실행합니다.
vue add typescript
그 다음 아래 구성에 따라 선택합니다(기존 js 코드와 TUIKit 중의 ts 코드를 동시에 지원할 수 있도록 부디 엄격히 아래 5개 옵션에 따라 구성하시기 바랍니다).
260706614-5e2fc00b-ace5-4843-bef6-c0e234225b5d.png (1514×360)

위의 단계를 완료한 후 프로젝트를 다시 실행하십시오!
vite를 통해 생성한 프로젝트 루트 다이렉트에서 다음을 실행합니다.
npm install -D typescript

3. 실행 시 오류: /chat-example/src/TUIKit/components/TUIChat /message-input/message-input-editor.vue .ts(8, 23)TS1005: expected.


위에서와 같은 오류 정보가 나타나는 원인은 당신이 설치한 @vue/cli 버전이 너무 낮기 때문입니다. 부디 당신의 @vue/cli 버전을 5.0.0 및 이상으로 확보하시기 바랍니다. 업그레이드 방식은 다음과 같습니다.
npm install -g @vue/cli@5.0.8

4. 실행 시 오류: Failed to resolve loader: sass-loader

260897345-1ba994d8-da51-4820-94e7-a7145b34750b.png (690×160)

위에서와 같은 오류 정보가 나타나는 원인은 sass 환경을 설치하지 않았기 때문입니다. 아래 명령을 실행하여 sass 환경을 설치하십시오.
npm i -D sass sass-loader@10.1.1

5. ESLint 기타 오류?

chat-uikit-vue를 src 디렉토리로 복사하여 취합할 때 로컬 프로젝트 코드 스타일과 일치하지 않음으로 인해 오류가 발생하면, 본 컴포넌트 디렉터리를 차단합니다. 예를 들어 프로젝트 루트 디렉토리에 .eslintignore 파일을 추가합니다.
# .eslintignore
src/TUIKit

6. vue/cli는 dev 모드에서 webpack 풀화면 overlay error 오류 정보 알림을 어떻게 끕니까?

프로젝트 루트 디렉토리의 vue.config.js에서 끌 수 있습니다.
webpack4
webpack3
module.exports = defineConfig({
...
devServer: {
client: {
overlay: false,
},
},
});
module.exports = {
...
devServer: {
overlay: false,
},
};

7. Component name "XXXX" should always be multi-word가 나타나면 어떻게 합니까?

IM TUIKit web에 사용되는 ESLint 버전은 v6.7.2입니다. 모듈명의 카멜 표기법에 대해 엄격한 검증을 하지 않습니다.
이 문제가 발생하면 .eslintrc.js 파일에서 다음과 같이 구성할 수 있습니다.
module.exports = {
...
rules: {
...
'vue/multi-word-component-names': 'warn',
},
};

8. ERESOLVE unable to resolve dependency tree가 나타나면 어떻게 합니까?

npm install 시 ERESOLVE unable to resolve dependency tree가 나타나면 종속성 설치 충돌을 의미하므로 다음 방식으로 설치할 수 있습니다.
npm install --legacy-peer-deps

9. 'vue packages version mismatch'과 같은 실행 오류가 발생하면 어떻게 해결합니까?

// vue2.7 프로젝트인 경우 프로젝트 루트 디렉터리에서 다음을 실행합니다.
npm i vue@2.7.9 vue-template-compiler@2.7.9
// vue2.6 프로젝트인 경우 프로젝트 루트 디렉터리에서 다음을 실행합니다.
npm i vue@2.6.14 vue-template-compiler@2.6.14

10. vite 프로젝트 npm run build 이후 ts 오류?


원인: package.json script의 "build": "vue-tsc && vite build" 중의 vue-tsc 명령으로 인해 발생합니다.

솔루션: vue-tsc를 삭제하시면 됩니다. "build": "vite build"


교류와 피드백

Telegram 기술 교류 그룹 또는 WhatsApp 교류 그룹에 가입하여 전문 앤지니어의 지원을 받아 당신의 문제를 해결할 수 있습니다.

관련 문서

Vue2 & Vue3 UIKit 관련:

Vue2 & Vue3 UIKit 논리계층: engine 관련