Get Started with Agora Chat UIKit for Web

Overview

agora-chat-uikit is a UI component library based on the Chat SDK. It provides pure UI components, module components containing chat business logic, and container components, which allow users to customize using renderX method. agora-chat-uikit provides a provider to manage data. The provider automatically listens for chat SDK events to update data and drive UI updates. Developers can use the library to quickly build custom IM applications based on actual business requirements.

Technical principles

UIKIt consists of three parts: UI component, mobx store for managing data, and chat SDK. UI components include container components, composite components module, and pure UI components. These components at different levels are currently available to you. You can reference any of these components to build your own applications. UIkit uses mobx to manage global data, and you can reference the rootStore to get all the data and the action method which can be used to modify the data. UIKit integrates the chat SDK internally and interacts with the server through the chat SDK.

Function

The agora-chat-uikit library provides the following functions:

• Automatic layout to match the width and height of the container.
• Send and receive messages, display messages, show the message unread count, clear messages, and support message types (including text, image, file, emoji, voice, video, combined message, and contact card message).
• Search for and delete a conversation and pin a conversation.
• Contacts list.
• Customize the UI.

Prerequisites

In order to follow the procedure in this page, you must have:

• React 16.8.0 or later
• React DOM 16.8.0 or later
• A valid Agora account
• A valid Agora project with an App Key

Compatible browsers

| Browser | Supported Version | | ------- | ----------------- | | IE | 11 or later | | Edge | 43 or later | | Firefox | 10 or later | | Chrome | 54 or later | | Safari | 11 or later |

Limitations

URL Preview Limitations：If a website does not have cross-origin resource sharing (CORS) configured, it may lead to issues with URL resolution. CORS is a security mechanism that restricts cross-origin requests initiated from a web browser. When a cross-origin request is made from a web page using JavaScript or other client-side technologies, the browser sends a preflight request (OPTIONS request) to confirm whether the target server allows the cross-origin request. If the target server is not properly configured for CORS, the browser rejects the cross-origin request, resulting in the inability to access and resolve the URL. It's important to note that CORS restrictions are enforced by the browser as a security policy, and they only apply to cross-origin requests initiated from the client-side. If URL resolution is performed on the server-side, it usually won't be subject to CORS limitations. In such cases, URL resolution can be directly performed on the server-side without the need for client-side scripting to initiate the request.

Project setup

1. Create a Web Chat UIKit project

# Install a CLI tool.
npm install create-react-app
# Create an my-app project.
npx create-react-app my-app
cd my-app

The project directory:

├── package.json
├── public # The static directory of Webpack.
│ ├── favicon.ico
│ ├── index.html # The default single-page app.
│ └── manifest.json
├── src
│ ├── App.css # The CSS of the app's root component.
│ ├── App.js # The app component code.
│ ├── App.test.js
│ ├── index.css # The style of the startup file.
│ ├── index.js # The startup file.
│ ├── logo.svg
│ └── serviceWorker.js
└── yarn.lock

2. Integrate the Web Chat UIKit

Install the Web Chat UIKit

• To install the Web Chat UIKit with npm, run the following command:

npm install agora-chat-uikit --save

• To Install the Web Chat UIKit with Yarn, run the following command:

yarn add agora-chat-uikit

Build the application using the agora-chat-uikit component

Import agora-chat-uikit into your code.

// App.js
import React, { Component, useEffect } from 'react';
import { UIKitProvider, Chat, ConversationList, useClient, rootStore } from 'agora-chat-uikit';
import 'agora-chat-uikit/style.css';

const appKey = 'you app key'; // your appKey
const user = ''; // your user ID
const accessToken = ''; // agora chat token

const conversation = {
  chatType: 'singleChat', // 'singleChat' || 'groupChat'
  conversationId: 'agora', // target user ID or group ID
  name: 'Agora', // target user nickname or group name
  lastMessage: {},
};
const ChatApp = () => {
  const client = useClient();
  useEffect(() => {
    client &&
      client
        .open({
          user,
          accessToken,
        })
        .then(res => {
          console.log('get token success', res);
          // create a conversation
          rootStore.conversationStore.addConversation(conversation);
        });
  }, [client]);

  return (
    <div>
      <div>
        <ConversationList />
      </div>
      <div>
        <Chat />
      </div>
    </div>
  );
};

class App extends Component {
  render() {
    return (
      <UIKitProvider
        initConfig={{
          appKey,
        }}
      >
        <ChatApp />
      </UIKitProvider>
    );
  }
}

export default App;

Run the project and send your first message

npm run start

Now, you can see your app in the browser.

For quick experience, you can use the default App Key and send several types of messages. Specifically, you can select a contact, enter your first message, and send it.

Note

If a custom App Key is used, no contact is available by default and you need to first add contacts or join a group.

Agora provides an open-source web Agora Chat UIKit project on GitHub, where you can clone and run the project or reference the logic to create a project that integrates agora-chat-uikit.

• How to get an Agora Chat token
• URL for source code of the Web Agora Chat UIKit
• URL for Agora Chat application using agora-chat-uikit

Component

Currently, agora-chat-uikit provides the following components:

• Container components: UIKitProvider， Chat，ConversationList, ContactList, Thread;
• Module components: BaseMessage，AudioMessage，FileMessage， VideoMessage，ImageMessage，TextMessage,CombinedMessage, UserCardMessage, ContactDetail, GroupDetail, Header，Empty，MessageList， ConversationItem，MessageInput，MessageStatus;
• Pure UI components: Avatar，Badge，Button，Checkbox，Icon，Modal，Tooltip, Input, UserItem;

Container components are as follows:

store

UIKit provides a rootStore that contains all the data. rootStore contains:

• initConfig: UIKit initializes data
• client: Chat SDK instance
• conversationStore: indicates the data related to the conversation list
• messageStore: indicates message-related data
• addressStore: indicates the address book data

How to customize

Here is an example of how to customize the chat component.

Modify component style

You can modify the style by passing in className, style, and prefix through the component props:

import { Chat, Button } from 'chatuim2';

const ChatApp = () => {
  return (
    <div>
      <Chat className="customClass" prefix="custom" />
      <Button style={{ width: '100px' }}>Button</Button>
    </div>
  );
};

Using custom components

Custom components can be rendered through the renderX method of container components:

import {Chat, Header} from 'agora-chat-uikit'

const ChatApp = () => {
  const CustomHeader = <Header back content="Custom Header">
  return(
    <div>
      <Chat renderHeader={(cvs) => CustomHeader}>
    </div>
  )
}

Modify Theme

The UIKit style is developed using the scss framework and defines a series of global style variables, including but not limited to global styles (main color, background color, rounded corners, borders, font size).

// need to use hsla
$blue-base: hsla(203, 100%, 60%, 1);
$green-base: hsla(155, 100%, 60%, 1);
$red-base: hsla(350, 100%, 60%, 1);
$gray-base: hsla(203, 8%, 60%, 1);
$special-base: hsla(220, 36%, 60%, 1);

$font-color: $gray-3;
$title-color: $gray-1;
$component-background: #fff;

$height-base: 36px;
$height-lg: 48px;
$height-sm: 28px;

// vertical margins
$margin-lg: 24px;
$margin-md: 16px;
$margin-sm: 12px;
$margin-xs: 8px;
$margin-xss: 4px;

// vertical paddings
$padding-lg: 24px;
$padding-md: 20px;
$padding-sm: 16px;
$padding-s: 12px;
$padding-xs: 8px;
$padding-xss: 4px;
// font
$font-size-base: 14px;
$font-size-lg: $font-size-base + 2px;
$font-size-sm: 12px;
$text-color: fade($black, 85%);

1. Use webpack for variable coverage:

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              additionalData: `@import "@/styles/index.scss";`,
            },
          },
        ],
      },
    ],
  },
};

2. Customize in create-react-app

Create an SCSS file with variables to override style.scss. Make sure that you import the files in the following order:

@import 'agora-chat-uikit/style.scss'; // agora-chat-uikit theme
@import 'your-theme.scss'; // your theme
@import 'agora-chat-uikit/components.scss'; // components style

If these cannot meet the customization requirements, you can also find the elements to cover the style of UIKit.

Community Contribution

If you want to add extra functions to agora-chat-uikit to share with others, you can fork our repository on GitHub and create a pull request. For any issues, please submit it on the repository. Thank you for your contribution!

Feedback

If you have any problems or suggestions regarding the sample projects, feel free to file an issue.

Reference

• Agora Chat SDK Product Overview
• Agora Chat SDK API Reference
• Agora Chat UIKit Components Story Book

Related resources

• Check our FAQ to see if your issue has been recorded.
• Dive into Agora SDK Samples to see more tutorials.
• Take a look at Agora Use Case for more complicated real use case.
• Repositories managed by developer communities can be found at Agora Community.
• For any integration issues, feel free to ask for help in Stack Overflow.

License

The sample projects are under the MIT license.