@tencent-rtc/mcp 1.0.1 → 1.0.2

package/resource/doc/chatuikit/react/integrate_tuichat_only_react.md

@@ -0,0 +1,202 @@
+## Applicable Scenarios
+
+Web & H5 platform, integrate independently private chat (1V1) or Group chat. This scenario is applicable for such as real estate consultancy, e-commerce customer service, remote insurance claims assessment.
+
+You can directly experience the chat below. Meanwhile, you can quickly try online code implementation through [**Experience Sandbox**](https://codesandbox.io/p/sandbox/trtc-chat-only-gmtmfw).
+<iframe src="https://sdk-web-1252463788.cos.ap-hongkong.myqcloud.com/im/demo/docs-example/sample-chat/index.html#/chatbox?page=intergrationchat" style="width:100%;height:700px;border:none" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="no-referrer-when-downgrade" allowfullscreen></iframe>
+
+
+## Development Environment Requirement
+- React version 18
+
+- TypeScript
+
+- [Node.js](https://nodejs.org/en/) version 18+
+
+- npm (version should match node version)
+
+
+## Chat-Uikit-React Integration
+
+### Step 1: Create Project
+
+Create a new React project named **chat-app** (select React 18 during project creation and recommend using the Typescript template), and follow the prompt to run the initial project.
+
+
+【shell】
+``` bash
+npm create rsbuild@latest
+```
+
+### Step 2: Download the Chat-Uikit-React Component
+
+Download [chat-uikit-react](https://www.npmjs.com/package/@tencentcloud/chat-uikit-react) via npm and use it in the project.
+
+
+【shell】
+``` bash
+npm i @tencentcloud/chat-uikit-react
+```
+
+### Step 3: Introduce the Chat-Uikit-React Component, Create and Open a Session to Chat
+
+> **Note:**
+> 
+
+> Note: The following code does not auto-fill `SDKAppID`, `userID`, or `userSig`. Retrieve related information in [procedure 4](https://write.woa.com/#step4) and replace them.
+> 
+
+
+> **Note:**
+> 
+> -   Call API [createC2CConversation](https://write.woa.com/document/155521474134589440) to create a one-to-one chat.
+> - Call API [createGroupConversation](https://write.woa.com/document/155521474134589440) to create a group chat.
+> - Ways to enter a chat:
+> - Call API [setActiveConversation](https://write.woa.com/document/155521474134589440), input conversationID to enter the chat page.
+
+
+Replace the content in App.tsx, or you can create a new component and introduce it. [Experience Sandbox ->](https://codesandbox.io/p/sandbox/trtc-chat-only-gmtmfw?from-embed=)
+``` typescript
+import {
+  UIKitProvider,
+  useLoginState,
+  LoginStatus,
+  useConversationListState,
+  Chat,
+  MessageList,
+  MessageInput,
+  ChatHeader,
+  useUIOpenControlState,
+  ChatSetting,
+  Search,
+  VariantType,
+} from "@tencentcloud/chat-uikit-react"
+
+export default function App() { 
+
+  const { isChatSettingOpen, isChatSearchOpen } = useUIOpenControlState();
+  const { setActiveConversation, createC2CConversation } = useConversationListState();
+  const { status } = useLoginState({
+    SDKAppID: 0, // Your SDKAppID, see procedure 4
+    userID: '',  // Your logged in UserID, see procedure 5
+    userSig: '', // Your userSig, see procedure 5
+    onSuccess() {
+      const userID = ''; // userID: recipient's userID
+      createC2CConversation(userID).then((conversation) => {
+        setActiveConversation(conversation.conversationID);
+      })
+    }
+  });
+
+  if (status !== LoginStatus.SUCCESS) {
+    return <div>loading...</div>;
+  }
+  
+  // Language support en-US(default) / zh-CN / ja-JP / ko-KR / zh-TW
+  // Theme supports light(default) / dark
+  return (
+    <div style={{display: 'flex', height: '100vh'}}>
+      <UIKitProvider language='en-US' theme='light'>
+        <Chat style={{ width: '100vw' }}>
+          <ChatHeader />
+          <MessageList />
+          <MessageInput />
+        </Chat>
+        {isChatSettingOpen && <ChatSetting />}
+        {isChatSearchOpen &&  <Search style={{ minWidth: '300px'}} variant={VariantType.EMBEDDED} />}
+      </UIKitProvider>
+    </div>   
+  );
+}
+```
+
+### Step 4: Creating an Application
+1. Log in to the [Chat Console](https://console.trtc.io/).
+
+2. Click "Create Application", enter your application name, then click "Create".
+
+
+   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100033438418/327c29cf622711f0a64452540099c741.png)
+
+3. After creation, you can see the application status, service version, SDKAppID, createTime, tag, and expiration time on the console overview page.
+
+
+   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100033438418/3340d098622711f0ad0f5254005ef0f7.png)
+
+
+### Procedure 5: Obtain UserID and UserSig
+- `userID`
+
+  - Click to enter the [Application](https://console.trtc.io/app) you created above. The `Chat` product entry will be shown in the left sidebar. Click to enter.
+
+  - After entering the Chat product subpage, click `Users` to enter the user management page.
+
+  - Click `Create account`, and a pop-up input box for account information will appear. If you are merely an ordinary member, we recommend you select the `General` data type.
+
+  - For a better experience in message sending and receiving and other features, we recommend creating two userIDs.
+
+
+      ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100033438418/322318b9622711f0ad0f5254005ef0f7.png)
+
+- `userSig`, usable development tools provided by the console to generate in real-time. Please click [Chat Console > Development Tools > UserSig Tools > Signature (UserSig) Generator](https://console.trtc.io/usersig).
+
+
+   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100033438418/323eb909622711f0a64452540099c741.png)
+
+
+### Step 6: Start Project
+
+Replace the SDKAppID, userID, and userSig in App.tsx, then run the command as follows:
+
+
+【shell】
+``` bash
+ npm run start
+```
+
+> **Note:**
+> 
+> 1. Please ensure the [procedure 3](https://write.woa.com/#step3) code has successfully replaced `SDKAppID`, `userID`, and `userSig`. If not replaced, it will lead to abnormal project performance.
+> 2. `userID` and `userSig` have a one-to-one relationship. Refer to [generate UserSig](https://trtc.io/document/39074?product=consoleguide).
+> 3. If the project fails to start, please check whether the [development environment requirement](https://write.woa.com/#required) are met.
+
+
+### Step 7: Send Your First Message
+
+enter the message in the input box and press **enter** to send.
+<iframe src="https://codesandbox.io/embed/gmtmfw?view=split&amp;module=%2Fsrc%2FApp.tsx" style="width:100%;height:750px;border:0;border-radius:4px;overflow:hidden" title="chat-react-test" allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking" sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"></iframe>
+
+
+## FAQs
+
+#### What Is UserSig
+
+UserSig is the password for user login to Chat, which is essentially the encrypted ciphertext of UserID and other information.
+
+#### How to Generate UserSig
+
+The UserSig issuance method involves integrating the UserSig calculation code into your server and providing a project-oriented API. When UserSig is required, your project initiates a request to the business server to obtain a dynamic UserSig. For more details, see [UserSig generation by the server](https://cloud.tencent.com/document/product/269/32688#GeneratingdynamicUserSig).
+
+> **Note:**
+> 
+
+> The example code in this document uses a solution to obtain UserSig by configuring SECRETKEY in client-side code. In this method, SECRETKEY can be easily decompiled and reverse-engineered. Once your key is leaked, attackers can steal your Tencent Cloud traffic. Therefore, **this method is only suitable for local debugging**. For the correct UserSig issuance method, please refer to the context before.
+> 
+
+
+#### Does React 17.X Version Support
+
+Currently does not support version 17.x. Only React ≥ v18.0 is supported.
+
+## Reference Documentation
+
+#### UIKit Related
+- [chat-uikit-react npm](https://www.npmjs.com/package/@tencentcloud/chat-uikit-react)
+
+- [Demo source code and running example](https://github.com/TencentCloud/chat-uikit-react)
+
+
+#### Implementing More Features, Refer to ChatEngine API Document
+- [chat-uikit-engine API manual](https://web.sdk.qcloud.com/im/doc/chat-engine/index.html)
+
+- [chat-uikit-engine npm](https://www.npmjs.com/package/@tencentcloud/chat-uikit-engine)

package/resource/doc/chatuikit/react/integrate_tuichat_react.md

@@ -0,0 +1,279 @@
+## Introduction
+
+chat-uikit-react is a react UI component library based on Tencent Cloud Chat SDK. It provides some common UI components, including session, chat, group and other features. Based on these well-designed UI components, you can quickly build elegant, reliable and scalable chat applications.
+
+You can directly experience the chat below. Meanwhile, you can quickly try online code implementation through [**Try On CodeSandbox**](https://codesandbox.io/p/sandbox/trtc-chat-full-48sffc?from-embed=).
+<iframe src="https://web.sdk.qcloud.com/im/demo/docs-example/sample-chat/index.html#/inbox?page=intergration" style="width:100%;height:700px;border:none" allow="camera; microphone; accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="no-referrer-when-downgrade" allowfullscreen></iframe>
+
+
+## Development Environment Requirement
+- React version 18
+
+- TypeScript
+
+- [Node.js](https://nodejs.org/en/) version 18+
+
+- npm (version should match node version)
+
+
+## chat-uikit-react Integration
+
+### Step 1: Create Project
+
+Create a new React project named **chat-app** (select React 18 during project creation and recommend using the Typescript template), and follow the prompt to set up the initial project.
+
+
+【shell】
+``` bash
+npm create rsbuild@latest
+```
+
+### Step 2: Download the Chat-Uikit-React Component
+
+Download [chat-uikit-react](https://www.npmjs.com/package/@tencentcloud/chat-uikit-react) via npm for use in the project.
+
+
+【shell】
+``` bash
+npm i @tencentcloud/chat-uikit-react
+```
+
+Copy the debug directory to the src/debug folder in the project directory. This is required when generating user signatures locally.
+
+
+
+
+【MacOS】
+``` bash
+cp -r node_modules/@tencentcloud/chat-uikit-react/debug ./src
+```
+
+
+【Windows】
+``` bash
+xcopy node_modules\@tencentcloud\chat-uikit-react\debug .\src\debug /i /e
+```
+
+### Step 3: Introducing the Chat-Uikit-React Component
+
+> **Note:**
+> 
+> - The following code does not include `SDKAppID`, `userID`, and `UserSig`. You need to replace them with the relevant information obtained in [Step 4](https://write.woa.com/document/108053210129276928).
+> - To respect the copyright of emoji designs, the Chat Demo/TUIKit project does not include large emoji graphics. Please replace them with your own designs or other emoji packs for which you hold the copyright before officially launching for commercial use. **The default smiley face emoji pack shown below is copyrighted by Tencent RTC** and is available for licensed use for a fee. If you need to obtain a license, please [submit a ticket](https://trtc.io/contact) contact us.
+
+> ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027202808/a7c853cf981a11ef834b525400f69702.png)
+> 
+
+
+Replace the content in App.tsx, or you can create a new component and import it. [**→ Experience in sandbox**](https://codesandbox.io/p/sandbox/trtc-chat-full-48sffc?from-embed=)**.**
+``` typescript
+import {
+  UIKitProvider,
+  useLoginState,
+  LoginStatus,
+  ConversationList,
+  Chat,
+  ChatHeader,
+  MessageList,
+  MessageInput,
+  useUIOpenControlState,
+  ChatSetting,
+  Search,
+  VariantType,
+  ContactList,
+  ContactInfo,
+} from "@tencentcloud/chat-uikit-react";
+import { useState } from "react";
+import * as GenerateTestUserSig from "./debug/GenerateTestUserSig-es";
+
+
+function App() {
+  const userID = '';        // TODO: Replace with your userID
+  const SDKAppID = 0;        // TODO: Replace with your SDKAppID (Notice: SDKAppID is of type number）
+  const SDKSecretKey = '';   // TODO: Replace with your SDKSecretKey
+
+  const { isChatSettingOpen, isChatSearchOpen } = useUIOpenControlState();
+  const [activeTab, setActiveTab] = useState('chats');
+
+  const { userSig } = GenerateTestUserSig.genTestUserSig({ 
+    userID,
+    SDKAppID,
+    SecretKey: SDKSecretKey,
+  });
+  
+  const { status } = useLoginState({
+    SDKAppID,
+    userID,
+    userSig,
+  })
+
+  if (status !== LoginStatus.SUCCESS) {
+    return <div>Loading...</div>
+  }
+  
+  // Language support en-US(default) / zh-CN / ja-JP / ko-KR / zh-TW
+  // Theme support light(default) / dark
+  return (
+    <UIKitProvider>
+      <div style={{ height: '100vh', width: '100vw', display: 'flex', flexDirection: 'row' }}>
+        <ul>
+          <li onClick={() => {setActiveTab('chats')}}>chats</li>
+          <li onClick={() => {setActiveTab('contacts')}}>contact</li>
+        </ul>
+        {
+          activeTab === 'chats' && (
+            <>
+              <ConversationList style={{ minWidth: '300px', maxWidth: '350px' }}/>
+              <Chat PlaceholderEmpty="No messages yet">
+                <ChatHeader />
+                <MessageList />
+                <MessageInput />
+              </Chat>
+              {isChatSettingOpen && <ChatSetting />}
+              {isChatSearchOpen &&  <Search style={{ minWidth: '300px'}} variant={VariantType.EMBEDDED} />}
+            </>
+          )
+        }
+        {
+          activeTab === 'contacts' && (
+            <>
+              <ContactList style={{ minWidth: '300px', maxWidth: '350px' }}/>
+              <ContactInfo 
+                PlaceholderEmpty="No contact yet"
+                onSendMessage={() => {setActiveTab('chats')}}
+                onEnterGroup={() => {setActiveTab('chats')}}
+              />
+            </>
+          )
+        }
+      </div>
+    </UIKitProvider>
+  );
+}
+
+export default App;
+```
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >Parameter</td>
+
+<td rowspan="1" colSpan="1" >Type</td>
+
+<td rowspan="1" colSpan="1" >Note</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >userID</td>
+
+<td rowspan="1" colSpan="1" >String</td>
+
+<td rowspan="1" colSpan="1" >Unique identifier of the user, defined by you, it is allowed to contain only upper and lower case letters (a-z, A-Z), numbers (0-9), underscores, and hyphens.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >SDKAppID</td>
+
+<td rowspan="1" colSpan="1" >Number</td>
+
+<td rowspan="1" colSpan="1" >The unique identifier for the audio and video application created in the [Tencent RTC Console](https://console.trtc.io/).</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >SDKSecretKey</td>
+
+<td rowspan="1" colSpan="1" >String</td>
+
+<td rowspan="1" colSpan="1" >The SDKSecretKey of the audio and video application created in the [Tencent RTC Console](https://console.trtc.io/).</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >userSig</td>
+
+<td rowspan="1" colSpan="1" >String</td>
+
+<td rowspan="1" colSpan="1" >A security protection signature used for user log in authentication to confirm the user's identity and prevent malicious attackers from stealing your cloud service usage rights.</td>
+</tr>
+</table>
+
+
+> **Explanation of UserSig：**
+> 
+
+> **Development environment**: If you are running a demo locally and developing or debugging, you can use the `genTestUserSig` (Refer to Step 3.2) function in the debug file to generate a 'userSig'. In this method, SDKSecretKey is vulnerable to decompilation and reverse engineering. Once your key is leaked, attackers can steal your Tencent Cloud traffic.
+> 
+
+> **Production environment**: If your project is going live, please use the [Server-side Generation of UserSig](https://trtc.io/document/34385) method.
+> 
+
+
+### Step 4: Create an application
+1. Log in to  [Chat Console](https://console.trtc.io/) .
+
+2. Click  **Create Application**, enter your application name, then  click  **Create**.
+
+
+   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027119864/cdc5fdb411ec11efa2935254005ac0ca.png)
+
+3. After creation, you can view the Application Status, service version, SDKAppID, creation time, Tag, and expiration time of the new application on the console overview page.
+
+   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027862798/c73f215c7cf411f0914f52540099c741.png)
+
+
+### Step 5: Start the Project
+
+Replace SDKAppID, UserID, and UserSig in App.tsx, then run the following command:
+
+
+【shell】
+``` bash
+ npm run dev
+```
+
+> **Note:**
+> 
+> 1. Please ensure that in Step 3 code, SDKAppID, UserID, and UserSig are all successfully replaced. Failure to replace them will result in abnormal project behavior.
+> 2. A `userID` corresponds to a `userSig`, for more information, see [Generating UserSig](https://trtc.io/document/39074?product=consoleguide).
+> 3. If the project fails to start, please check whether the [development environment requirements](https://write.woa.com/document/108053210129276928) are met.
+
+
+### Step 6: Send your first message
+
+Enter your message in the input box and press Enter to send.
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027119864/efc5e925595711efb36952540075b605.png)
+
+## FAQs
+
+#### What is UserSig?
+
+A UserSig is a password for users to log in to Chat. It is essentially the ciphertext generated by encrypting information such as the UserID.
+
+#### How can I generate a UserSig?
+
+The issuance method for UserSig involves integrating the calculation code of UserSig into your server, and providing an interface oriented towards your project. When UserSig is needed, your project sends a request to the business server to access the dynamic UserSig. For more information, please see [How to Generate a UserSig on the Server](https://trtc.io/document/39074?product=consoleguide).
+
+> **Note:**
+> 
+
+> The exemplary code provided in this document retrieves the UserSig by embedding the SECRETKEY in the client code. This approach makes the SECRETKEY highly susceptible to decompilation and reverse engineering. Once your encryption key is compromised, attackers can misappropriate your Tencent Cloud traffic. Hence, **this procedure is exclusively recommended for running functional debugging locally**. For the correct issuance of UserSig, please refer to the previous sections.
+> 
+
+
+## Communication and Feedback
+
+Join the [Telegram Technical Exchange Group](https://t.me/tencent_imsdk) or [WhatsApp Exchange Group](https://chat.whatsapp.com/IVa11ZkVmKTEwSWsAzSyik) to enjoy support from professional engineers and solve your problems.
+
+## Documentation
+
+#### UIKit  Related:
+- [chat-uikit-react npm](https://www.npmjs.com/package/@tencentcloud/chat-uikit-react)
+
+- [Demo Source Code and Running Example](https://github.com/TencentCloud/chat-uikit-react)
+
+
+#### For more features, refer to the ChatEngine API documentation:
+- [chat-uikit-engine API Manual](https://web.sdk.qcloud.com/im/doc/chat-engine/index.html)
+
+- [chat-uikit-engine npm](https://www.npmjs.com/package/@tencentcloud/chat-uikit-engine)
+
+