UI Kit quickstart

Instant messaging connects people wherever they are and allows them to communicate with others in real time. Agora offers an open-source Chat UI Kit project on GitHub. With built-in user interfaces for key Chat features, the Agora Chat UI Kit enables you to quickly embed real-time messaging into your app without requiring extra effort on the UI.

For the latest Agora Chat UIKit documentation, refer to the UIKit 2.x Documentation GitHub repository.

Legacy UIkit 1.x documentation

This page shows sample code to add peer-to-peer messaging into your app by using the Agora Chat UI Kit.

Understand the tech

The following figure shows the workflow of how clients send and receive peer-to-peer messages:

Chat UI kit workflow

Clients retrieve a token from your app server.
Client A and Client B log in to Agora Chat.
Client A sends a message to Client B. The message is sent to the Agora Chat server, and the server delivers the message to Client B. When Client B receives the message, the SDK triggers an event. Client B listens for the event and gets the message.

Prerequisites

Android

If your target platform is Android:

macOS 10.15.7 or later, or Windows 10 or later
Android Studio 2021.3.1 or later, including JDK 1.8 or later
Visual Studio Code latest
React Native 0.63.5 or later
CocoaPods package management tool if your operating system is macOS.
Powershell 5.1 or later if your operating system is Windows.
Node.js 16.18.0 or later, including npm package management tool (Homebrew installation is recommended)
TypeScript 4.0 or later
Yarn 1.22.19 or later
Watchman debugging tool
npm and related tools
Expo 6.0.0 or later
A physical or virtual mobile device running Android 6.0 or later

iOS

If your target platform is iOS:

macOS 10.15.7 or later
Xcode 13.4 or later, including command line tools
Objective-C 2.0 or later
Visual Studio Code latest
React Native 0.63.5 or later
Node.js 16.18.0 or later, including npm package management tool (Homebrew installation is recommended)
TypeScript 4.0 or later
CocoaPods package management tool
Yarn 1.22.19 or later
Watchman debugging tool
npm and related tools
Expo 6.0.0 or later
A physical or virtual mobile device running iOS 10.0 or later

For more information, see Setting up the environment.

Project setup

To create a new project using the React Native UI Kit, take the following steps:

Create a new React-Native application project

npx react-native init RNUIkitQuickExamle --version 0.71.11

Initialize your project
```
yarn && yarn run env
```

Add the required dependencies:

yarn add @react-native-async-storage/async-storage \
@react-native-camera-roll/camera-roll \
@react-native-clipboard/clipboard \
@react-native-firebase/app \
@react-native-firebase/messaging \
react-native-audio-recorder-player \
react-native-agora-chat \
react-native-agora-chat-uikit \
react-native-create-thumbnail \
react-native-document-picker \
react-native-fast-image \
react-native-file-access \
react-native-get-random-values \
react-native-image-picker \
react-native-permissions \
react-native-safe-area-context \
react-native-screens \
react-native-video

Configure the iOS platform.

Add the following content to the ios/Podfile file:

target 'RNUIkitQuickExamle' do

pod 'GoogleUtilities', :modular_headers => true
pod 'FirebaseCore', :modular_headers => true

permissions_path = File.join(File.dirname(`node --print "require.resolve('react-native-permissions/package.json')"`), "ios")
pod 'Permission-Camera', :path => "#{permissions_path}/Camera"
pod 'Permission-MediaLibrary', :path => "#{permissions_path}/MediaLibrary"
pod 'Permission-Microphone', :path => "#{permissions_path}/Microphone"
pod 'Permission-Notifications', :path => "#{permissions_path}/Notifications"
pod 'Permission-PhotoLibrary', :path => "#{permissions_path}/PhotoLibrary"

end

Add the following content to the ios/RNUIkitQuickExamle/Info.plist file:

<dict>
    <key>NSCameraUsageDescription</key>
    <string></string>
    <key>NSMicrophoneUsageDescription</key>
    <string></string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string></string>
</dict>

Configure the Android platform.

Add the following content to the android/build.gradle file:

buildscript {
    ext {
        kotlinVersion = '1.6.10'
        if (findProperty('android.kotlinVersion')) {
            kotlinVersion = findProperty('android.kotlinVersion')
        }
    }
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
    }
}

Add the following content to the android/app/src/main/AndroidManifest.xml file:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
</manifest>

Implementation

To initialize the UI Kit, log in to the server, and enter the chat page, take the following steps:

Initialize the UI Kit

export const App = () => {
    return (
        <UikitContainer
        option={{
            appKey: appKey,
            autoLogin: autoLogin,
            debugModel: debugModel,
        }}
        >
        <NavigationContainer>
            <Root.Navigator initialRouteName="Main">
            <Root.Screen name="Main" component={MainScreen} />
            <Root.Screen name="Chat" component={ChatScreen} />
            </Root.Navigator>
        </NavigationContainer>
        </UikitContainer>
    );
};

Display Chat details

export function ChatScreen({
route,
}: NativeStackScreenProps<typeof RootParamsList>): JSX.Element {
    return (
        <ScreenContainer mode="padding" edges={['right', 'left', 'bottom']}>
        <ChatFragment
            screenParams={{
            params: route.params as any,
            }}
        />
        </ScreenContainer>
    );
}

Test your app

To set up and run the React Native Chat UI Kit example app:

Clone the Chat UI Kit for React Native repository.

git clone https://github.com/AgoraIO-Usecase/AgoraChat-UIKit-rn.git

Initialize the project by running the following commands in a terminal:
```
yarn && yarn run example-env && yarn run sdk-version
```

Configure the necessary parameters.

In the example project, open example/src/env.ts and fill in the information.

export const test = false; // test mode
export const appKey = ''; // from Agora console
export const id = ''; // default user id
export const ps = ''; // default password or token
export const accountType = 'agora';

For the examples/callkit-example project, add appKey and other values to the examples/callkit-example/src/env.ts file.

Configure the FCM file.
1. In the example project, make the following changes for each platform:
  - For Android, put the google-services.json file under the examples/android/app folder.
  - For iOS, move GoogleService-Info.plist to the example/iOS/ChatUikitExample folder.
2. In the examples/callkit-example project:
  - For Android, move the file google-services.json to the examples/callkit-example/android/app folder.
  - For iOS, place GoogleService-Info.plist under the examples/callkit-example/iOS/ChatCallkitExample folder.
Run the sample project

Execute the following inside a terminal to compile and run the React Native Chat UI Kit example app:
- For Android:
```
cd example && yarn run Android
```
- For iOS:
```
cd example && yarn run pods && yarn run iOS
```

Reference

UI Kit Details
- UIKit
- UIKit example
Take a look at the Quick Start for UIKit project to experience the fastest and easiest integration.
CallKit Details
- CallKit
- CallKit example
Take a look at the Quick Start for CallKit project to experience the fastest and easiest integration.

Understand the tech

Prerequisites

Android

iOS

Project setup

Implementation

Test your app

Reference

Contact Us

Contact Us