This document describes how to quickly integrate the Tencent Cloud Chat SDK into your React Native project.
Note:
Integrating @tencentcloud/chat into your React Native project requires downloading version 3.4.3 or later.
Integrating tim-upload-plugin into your React Native project requires downloading version 1.4.0 or later.
Environment Requirements
Platform
Version
React Native
v0.75.0 or later.
Android
Android Studio 3.5 or later. The app requires Android 4.1 or later devices.
iOS
Xcode 11.0 or later. For testing with a real device, make sure that your project has a valid developer signature.
Node
Version 18.0 or later.
Configuring the development environment
If this is your first time developing a React Native project, refer to the React Native official steps set-up-your-environment to configure the development environment.
If you encounter environment problems when creating or compiling the project, you can run npx react-native doctor for environment diagnostics.
Create a project (can be skipped if you already have one)
npx react-native@latest init MyChatApp
npm react-native creates projects with Android gradle version 8.8. If your Android gradle version is lower than 8.8, please open Android Studio to sync the gradle version.
Integrate Chat SDK
Integrate the Chat SDK into your React Native project using npm.
You can integrate the upload plugin tim-upload-plugin for faster and safer upload of rich media resources.
Enhance the user experience in a poor network environment or during network switching by integrating @react-native-community/netinfo.
You must have the correct SDKAppIDto proceed with the initialization.
SDKAppIDis the identifier for a Tencent Cloud Chat application. We recommend applying for a new SDKAppID for each independent app. Messages between different SDKAppIDs are inherently isolated and cannot be interoperated.
You can view all SDKAppIDs in the Chat Console. Click Create application to create a new application with a new SDKAppID.
Import the Chat SDK and initialize it in your project's App.tsx.
This is triggered when the SDK enters the ready state. After the accessing side listens to this event, it can call SDK APIs to send messages or use other SDK features.
letonSdkReady=function(event){
// After listening to the SDK ready event, you can make API calls
This is triggered when the SDK enters the not-ready state. At this time, the accessing side will not be able to use features like sending messages via the SDK. To resume usage, the accessing side needs to call the login interface and drive the SDK to enter the ready state.
When the SDK receives new messages from one-on-one chat, group chat, group prompts, or group system notifications, the accessing side can traverse event.data to obtain the message list data and render it to the UI.
letonMessageReceived=function(event){
// event.data - An array that stores `Message` objects - [Message]
// This indicates that the account is already logged in. This login attempt is a duplicate login.
console.log(imResponse.data.errorInfo);
}
}).catch(function(imError){
// Information related to login failure
console.warn('login error:', imError);
});
Compile and run the React Native application
To compile and run the project, you need to use a real device or an emulator. A real device is recommended. You can refer to the React Native official website running-on-device to connect a real device for debugging.
Android
iOS
1. Enable Developer Mode on your phone, and turn on the USB Debugging switch.
2. Connect your phone via USB. It's recommended to select the Transfer files option, do not choose the Charging only option.
3. After confirming the successful connection of your phone, execute npm run android to compile and run the project.
npm run android
1. Connect your mobile phone with a USB cable, and open the ios directory of the project using Xcode.
2. Configure the signing information according to the React Native official website running-on-device.
3. Go to the ios directory and install dependencies.
cd ios
pod install
4. Go back to the root directory and execute npm run ios to compile and run the project.
cd../
npm run ios
Integrate third-party module
If you need to implement features like sending Images, Videos, Files, Voice, it is recommended to use the third-party modules provided below.
Select Images and Videos, Take Photo, Shoot Video, we recommend that you integrate react-native-image-picker.
To enable VoiceMessage to play across all platforms, packaging the iOS app requires specifying VFormatIDKeyIOS as AVEncodingOption.aac for voice recording.
To use the album, camera, and microphone, you need to configure the corresponding permissions. After configuring, you need to recompile and run the project to ensure effectiveness.
Android
iOS
In the android directory, find app/src/main/AndroidManifest.xml and add the following permissions:
In the ios directory, find Info.plist and add the following permissions:
<key>NSCameraUsageDescription</key>
<string>We need access to your camera to take photos</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your album to select photos</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need access to your microphone to record audio</string>
Custom Definition Rich Media Message File Structure
If you choose other third-party plugins to select pictures, videos, files, and record voice, please assemble the file according to the following structure:
Image
Video
File
Voice
uri,fileName,type,width,height is required, fileSizeis optional if not available.
const file ={
uri:'xxx',
fileName:'xxx',
fileSize:1,
type:'xxx',
width:1,
height:1,
};
uri,fileName,type are required, and the typeformat must be **/*. fileSizeand durationare optional if not available.
const file ={
uri:'xxx',
fileName:'xxx',
fileSize:1,
type:'xxx',
duration:0,
};
uri,size,name are required, and sizemust be greater than 0.
const file ={
uri:'xxx',
name:'xxx',
size:1,
};
uri,fileName,duration are required. durationis measured in milliseconds (ms). fileSizeis optional if not available.
const file ={
uri:'xxx',
fileName:'xxx',
fileSize:1,
duration:0,
};
FAQs
1. When running npm run android and an error occurs as shown in the image, please reset the environment variables in the project root directory.