@tencent-rtc/mcp 1.3.1 → 1.3.2

package/resource/doc/roomkit/vue/integration.md

@@ -0,0 +1,479 @@
+TUIRoomKit is an audio/video conference UI application launched by Tencent Cloud. This upgrade introduces a brand new Atomicx component integration solution, allowing developers to flexibly combine these atomized components to build personalized conference interfaces.
+
+This document will help you integrate TUIRoomKit (Atomicx version) into your existing Vue 3 project, and introduce how to customize the styles, layout, and features of TUIRoomKit.
+
+> **Note:**
+> 
+
+> TUIRoomKit (Atomicx version) currently only supports PC-side Vue3 projects. If your business needs to support Vue2.x framework or H5 platform, please refer to [Legacy TUIRoomKit Quick Integration](https://write.woa.com/document/196568527013543936).
+> 
+
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/30581b7bd73111f0ab505254001c06ec.png)
+
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/31045da2d73111f097cb5254005ef0f7.png)
+
+
+## Prerequisites
+
+### Activate Service
+
+Please refer to [Activate Service](https://cloud.tencent.com/document/product/647/104842) to get the TUIRoomKit trial version, and obtain the following information on the [Application Management](https://console.cloud.tencent.com/trtc) page:
+- **SDKAppID**: Application identifier, Tencent Cloud completes billing statistics based on `SDKAppID`.
+
+- **SDKSecretKey**: Application secret key, used for secret key information in initialization configuration files.
+
+
+### Environment Preparation
+- **Node.js**: ≥ 18.19.1 (recommended to use official LTS version).
+
+- **Vue**: ≥ 3.4.21.
+
+- **Modern Browsers**: Modern browsers that support [WebRTC APIs](https://cloud.tencent.com/document/product/647/17249#.E6.94.AF.E6.8C.81.E7.9A.84.E5.B9.B3.E5.8F.B0).
+
+- **Devices**: Camera, microphone, speakers.
+
+
+## Source Code Integration
+
+### Step 1: Install Project Dependencies
+
+Install the following dependencies in your business project.
+
+
+
+
+【npm】
+``` bash
+npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
+```
+
+
+【pnpm】
+``` bash
+pnpm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
+```
+
+
+【yarn】
+``` bash
+yarn add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
+```
+
+### Step 2: Configure Development Environment
+
+If your project does not yet support TypeScript and SCSS, please install the corresponding environment dependencies first. If already installed, you can skip this step.
+
+
+
+
+【npm】
+``` bash
+npm install typescript sass -S -D
+```
+
+
+【pnpm】
+``` bash
+pnpm install typescript sass -S -D
+```
+
+
+【yarn】
+``` bash
+yarn add typescript sass -S -D
+```
+
+### Step 3: Copy Core Source Code Files
+
+Clone the TUIRoomKit GitHub repository and enter the PC-side Vue3 sample directory.
+``` bash
+git clone https://github.com/Tencent-RTC/TUIRoomKit.git --depth=1
+cd TUIRoomKit/Web/example/atomicx-vite-vue3-ts
+```
+
+Copy the core source code files under the `TUIRoomKit/Web/example/atomicx-vite-vue3-ts/src` path to your business project.
+
+> **Note:**
+> 
+
+> When copying source code files, please ensure merging with existing folders in your project, avoid directly overwriting existing folders with the same names.
+> 
+
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >Source Path (Sample Project)</td>
+
+<td rowspan="1" colSpan="1" >Target Path (Your Project)</td>
+
+<td rowspan="1" colSpan="1" >Description</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >src/assets/</td>
+
+<td rowspan="1" colSpan="1" >src/assets/</td>
+
+<td rowspan="1" colSpan="1" >Contains static resources such as background images and icons.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >src/components/</td>
+
+<td rowspan="1" colSpan="1" >src/components/</td>
+
+<td rowspan="1" colSpan="1" >Contains all TUIRoomKit atomic UI components</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >src/hooks/</td>
+
+<td rowspan="1" colSpan="1" >src/hooks/</td>
+
+<td rowspan="1" colSpan="1" >Contains TUIRoomKit business logic processing</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >src/i18n/</td>
+
+<td rowspan="1" colSpan="1" >src/i18n/</td>
+
+<td rowspan="1" colSpan="1" >Contains multi-language configuration files</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >src/utils/</td>
+
+<td rowspan="1" colSpan="1" >src/utils/</td>
+
+<td rowspan="1" colSpan="1" >Contains common utility functions</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >src/config/</td>
+
+<td rowspan="1" colSpan="1" >src/config/</td>
+
+<td rowspan="1" colSpan="1" >Contains `basic-info-config.js` and other application configuration information (focus on this file for first-time integration)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >src/views/home.vue</td>
+
+<td rowspan="1" colSpan="1" >src/views/home.vue</td>
+
+<td rowspan="1" colSpan="1" >This page contains device detection and room creation/join entry features</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >src/views/room.vue</td>
+
+<td rowspan="1" colSpan="1" >src/views/room.vue</td>
+
+<td rowspan="1" colSpan="1" >This page is the core meeting interface of TUIRoomKit, integrating complete header, video layout, control bar and sidebar panels</td>
+</tr>
+</table>
+
+
+### Step 4: Configure Page Routes
+
+Please configure your Vue Router to map home.vue to the homepage and room.vue to the meeting room page.
+
+> **Note:**
+> 
+> - If your business project already has a `src/router/index.ts` file, please merge the following content into the existing code.
+> - If routes have not been configured yet, please create a new `src/router/index.ts` file and add the following configuration.
+
+``` typescript
+// src/router/index.ts example configuration
+import { createRouter, createWebHistory } from 'vue-router';
+import Home from '../views/home.vue'; 
+import Room from '../views/room.vue';     
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/',
+      redirect: '/home',
+    },
+    {
+      path: '/home',
+      name: 'Home',
+      component: Home,
+    },
+    {
+      path: '/room',
+      name: 'Room',
+      component: Room,
+    },
+  ],
+});
+
+export default router;
+```
+
+### Step 5: Configure App.vue File
+
+You need to merge the following content into the App.vue file in your project to configure global UI styles and user login logic:
+- Configure global `UIKitProvider`: Import the `UIKitProvider` component and set default theme and language;
+
+- Import page routes: Render <router-view />;
+
+- User login: Execute login and setSelfInfo in the `onMounted` hook;
+
+   ``` typescript
+   <template>
+     <!-- Step 1: Configure global UIKitProvider -->
+     <UIKitProvider theme="light" language="zh-CN">
+       <!-- Step 2: Import page routes -->
+       <router-view />
+     </UIKitProvider>
+   </template>
+    
+    <!-- Note: Add lang="ts" to enable TypeScript support -->
+   <script setup lang="ts">
+   import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+   import { onMounted } from 'vue';
+   import { SDKAPPID, genTestUserSig } from './config/basic-info-config';
+   import { RoomEvent, useLoginState, useRoomModal } from 'tuikit-atomicx-vue3/room';
+   
+   // step 3: User login
+   const { login, setSelfInfo } = useLoginState();
+   const { handleErrorWithModal } = useRoomModal();
+   const userId = `user_${Math.ceil(Math.random(0,1)*999)}`;
+   const userName = userId;
+   const userSig = genTestUserSig(userId);
+   onMounted(async () => {
+     try {
+       await login({
+         userId,
+         userSig,
+         sdkAppId: SDKAPPID,
+       });
+       await setSelfInfo({
+         userName,
+         avatarUrl: '',
+       });
+     } catch (error: any) {
+       console.error('Login failed:', error);
+       handleErrorWithModal(error);
+     }
+   });
+   </script>
+   
+   <!-- Step 4: Configure global styles (these styles are used to override default styles of new projects built with scaffolding, can be configured as needed) -->
+   <style>
+   html, body {
+     padding: 0 !important;
+     margin: 0 !important;
+   }
+   
+   #app {
+     width: 100% !important;
+     height: 100% !important;
+     padding: 0 !important;
+     margin: 0 !important;
+     max-width: 100% !important;
+     max-height: 100% !important;
+     text-align: left !important;
+     overflow: hidden;
+   }
+   </style>
+   ```
+
+### Step 6: Configure src/main.ts File
+
+Merge the route and multi-language configuration into the entry file src/main.ts in your project:
+
+> **Note:**
+> 
+
+> If the entry file in your project is a js file, please change the file extension to src/main.ts.
+> 
+
+``` typescript
+// Step 1: Configure page routes
+import router from './router/index';
+const app = createApp(App);
+// --- New code below ----
+app.use(router);
+// --- New code above ----
+app.mount('#app');
+
+// Step 2: Configure multi-language resources
+import { i18next } from '@tencentcloud/uikit-base-component-vue3';
+import { enResource, zhResource } from './i18n';
+export const addI18n = (lng: string, resource: any, deep = true, overwrite = false) => {
+  i18next.addResourceBundle(lng, 'translation', resource.translation, deep, overwrite);
+};
+addI18n('en-US', { translation: enResource }, true, true);
+addI18n('zh-CN', { translation: zhResource }, true, true);
+```
+
+## Start Project
+
+### Configure Application Information
+
+Find the `src/config/basic-info-config.js` configuration file in your project directory, and fill in the `SDKAppID` and `SDKSecretKey` you obtained from the Tencent Cloud Console into the corresponding variables.
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/2fc2dd3dd73111f091e252540044a08e.png)
+
+
+> **Warning:**
+> 
+> - In the Demo example in this document, authentication is performed by configuring `SDKSecretKey` in client-side code, but `SDKSecretKey` can be easily decompiled and reverse engineered. Once the key is leaked, attackers can steal your Tencent Cloud traffic. Therefore, **this method is only suitable for local Demo testing and function debugging**. 
+> - **In formal production environments**, it is recommended to generate UserSig on your server side. When UserSig is needed, have your App request dynamic UserSig from the business server for authentication. For details, see [How to Calculate UserSig in Formal Operation Phase?](https://cloud.tencent.com/document/product/647/17275#formal)
+
+
+### Start Development Server
+
+
+
+
+【npm】
+``` bash
+npm run dev
+```
+
+
+【pnpm】
+``` bash
+pnpm run dev
+```
+
+
+【yarn】
+``` bash
+yarn run dev
+```
+
+After successful startup, please open the debug address (usually http://localhost:5173) in your browser to access the application. You will see the meeting interface as shown below:
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/312e7796d73111f091e252540044a08e.png)
+
+
+## UI Customization
+
+### Theme and Language
+
+Modify the default values for theme and language by configuring the parameters of `UIKitProvider` in App.vue.
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >UIKitProvider Parameter</td>
+
+<td rowspan="1" colSpan="1" >Available Values</td>
+
+<td rowspan="1" colSpan="1" >Default Value</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >theme</td>
+
+<td rowspan="1" colSpan="1" >"light" \| "dark"</td>
+
+<td rowspan="1" colSpan="1" >"light"</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >language</td>
+
+<td rowspan="1" colSpan="1" >"zh-CN" \| "en-US"</td>
+
+<td rowspan="1" colSpan="1" >"en-US"</td>
+</tr>
+</table>
+
+``` typescript
+<UIKitProvider theme="light" language="zh-CN">
+  <router-view />
+</UIKitProvider>
+ 
+<script setup lang="ts">
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+```
+
+### Room Stream Layout
+
+TUIRoomKit currently supports three stream layouts: grid, sidebar, and top bar. The default is grid layout.
+``` typescript
+// src/views/room.vue
+// Change default video stream layout to sidebar layout
+const participantViewLayout = ref(RoomLayoutTemplate.SidebarLayout);
+function handleLayoutUpdate(layout: RoomLayoutTemplate) {
+  participantViewLayout.value = layout;
+}
+
+// Change default video stream layout to top bar layout
+const participantViewLayout = ref(RoomLayoutTemplate.CinemaLayout);
+function handleLayoutUpdate(layout: RoomLayoutTemplate) {
+  participantViewLayout.value = layout;
+}
+```
+
+### Custom Video Stream Widget
+
+The default TUIRoomKit video stream widget is shown in the image. If you need to customize the video stream widget, please modify the `src/components/RoomLayoutView/ParticipantViewUI/ParticipantViewUI.vue` component.
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/2fab38f2d73111f0929b525400bf7822.png)
+
+
+### Configure User Contact List
+
+The TUIRoomKit scheduled meeting user selection list and in-meeting call user selection list default to displaying the user relationship chain list. To batch import user relationship chain, refer to the following steps:
+
+Step 1: Use the [Account Management > Import Multiple Accounts](https://cloud.tencent.com/document/product/269/4919) REST API interface to batch import user accounts;
+
+Step 2: Use the [Friend Management > Import Friends](https://cloud.tencent.com/document/product/269/8301) REST API interface to batch import user relationship chain;
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/32637a07d73111f0ab505254001c06ec.png)
+
+
+## FAQ
+
+#### **TUIRoomKit works normally during local development, but cannot properly capture user's camera or microphone devices after deployment to online environment?**
+- **Cause Analysis:** For security and privacy protection, browsers have strict restrictions on capturing audio/video devices (microphone, camera). Capture operations are only allowed in secure environments. Secure environment protocols include: https://, localhost, file://, etc. The HTTP protocol is considered insecure, and browsers will prohibit access to media devices by default.
+
+- **Solution:** If everything works normally in local (localhost) testing, but capture fails after deployment, please immediately check whether your webpage is deployed on the HTTP protocol. You must use the HTTPS protocol to deploy your webpage and ensure you have a valid security certificate.
+
+- **Related Resources:** For more details about URL domain and protocol restrictions, please see [URL Domain and Protocol Restrictions](https://cloud.tencent.com/document/product/647/17249#URL-.E5.9F.9F.E5.90.8D.E5.8D.8F.E8.AE.AE.E9.99.90.E5.88.B6).
+
+
+#### **Does TUIRoomKit support integration using iframe?**
+
+Yes. When integrating TUIRoomKit using iframe, you need to configure the allow attribute in the iframe tag to grant necessary browser permissions (microphone, camera, screen sharing, fullscreen, etc.), example as follows: 
+``` typescript
+// Enable microphone, camera, screen sharing, fullscreen permissions
+<iframe allow="microphone; camera; display-capture; display; fullscreen;">
+```
+
+#### Does TUIRoomKit support setting intranet proxy?
+
+Yes. Please refer to the following guide to set intranet proxy parameters. For more intranet proxy information, please refer to [Dealing with Firewall Restrictions](https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-34-advanced-proxy.html).
+``` typescript
+// Please set intranet proxy parameters before entering the room
+import TUIRoomEngine from '@tencentcloud/tuiroom-engine-js';
+import { useRoomEngine } from 'tuikit-atomicx-vue3/room';
+const { roomEngine } = useRoomEngine();
+
+TUIRoomEngine.once('ready', () => {
+  const trtcCloud = roomEngine.instance?.getTRTCCloud()；
+  trtcCloud.callExperimentalAPI(JSON.stringify({
+    api: 'setNetworkProxy',
+    params: {
+      websocketProxy: "wss://proxy.example.com/ws/",
+      turnServer: [{
+        url: '14.3.3.3:3478',
+        username: 'turn',
+        credential: 'turn',
+      }],
+      iceTransportPolicy: 'relay',
+    },
+  }));
+});
+```
+
+## Contact Us
+
+If you have any questions or suggestions during the integration or usage process, please feel free to [contact us](https://cloud.tencent.com/document/product/269/59590) to submit feedback.