快速开始（含 UIKIT）

即时通讯将各地人们连接在一起，实现实时通信。即时通讯 IM UIKit 内置了用户界面（UI）提供会话列表和联系人列表，使你可将实时通讯嵌入到你的应用程序，而无需在 UI 上进行额外操作。

本页展示如何使用即时通讯 IM UIKit 将单聊消息发送和接收的逻辑添加到应用程序中。

技术原理

下图展示在客户端发送和接收单聊文本消息的工作流程。

如上图所示，实现单聊消息的步骤如下：

1. 客户端向你的应用服务器请求 Token，你的应用服务器返回 Token。
2. 客户端 A 和客户端 B 使用获得的 Token 登录声网即时通讯系统。
3. 客户端 A 发送消息到声网即时通讯服务器。
4. 声网即时通讯服务器将消息发送到客户端 B，客户端 B 接收消息。

App 客户端登录声网即时通讯系统需要以下信息：

• AppKey：声网随机生成的字符串，用于识别你的 app，可从声网控制台获取。
• 用户 ID：用户的唯一标识。你需要自行设置用户 ID，并确保它在项目内是唯一的。
• Token：在测试或生产环境中，你的 app 客户端会从你的应用服务器中获取 Token。

前提条件

开始前，请确保你的开发环境满足以下要求：

• React 16.8.0 或以上版本。
• React DOM 16.8.0 或以上版本。
• 支持的浏览器和版本如下：
  • Internet Explorer：11 或以上
  • Edge：43 或以上
  • Firefox：10 或以上
  • Chrome：54 或以上
  • Safari：11 或以上
• 有效的声网账号。
• 开启了即时通讯 IM 服务。
• 有效的 App Key 和用户 token。

项目设置

本节介绍了如何创建应用程序并将聊天 UIKit 添加到项目中。

1. 在终端中，运行以下命令创建一个应用程序：

   # 安装 CLI 工具
   npm install create-react-app
   # 构建一个 my-app 的项目
   npx create-react-app my-app
   cd my-app

   成功创建应用程序后，项目结构如下：

   my-app
   ├── package.json
   ├── public                  # webpack 的配置的静态目录。
   │   ├── favicon.ico
   │   ├── index.html          # 默认的单页面应用，是最终的 HTML 的基础模板。
   │   └── manifest.json
   ├── src
   │   ├── App.css             # App 根组件的 css。
   │   ├── App.js              # App 组件代码。
   │   ├── App.test.js
   │   ├── index.css           # 启动文件样式。
   │   ├── index.js            # 启动文件。
   │   ├── logo.svg
   │   └── serviceWorker.js
   └── yarn.lock

2. 运行以下其中一个命令，将即时通讯服务 UIKit 添加到您的项目中。

• 若利用 npm 安装，运行以下命令：

   npm install agora-chat-uikit --save

• 使用 yarn 安装，运行以下命令：

   yarn add agora-chat-uikit

操作步骤

即时通讯 IM Web UIKit 包含 EaseApp，用于实现会话列表，可在大多数聊天用例中快速启动实时聊天应用。

下文介绍如何利用 EaseApp 快速实现单聊。

1. 导入 EaseApp。

   打开 my-app/src/App.js，利用以下内容替换代码：

    // App.js
    import React, {Component} from 'react';
    import { EaseApp } from "agora-chat-uikit"
    import './App.css';
   
    class App extends Component {
    render() {
        return (
        <div className="container">
            <EaseApp
                // 你的项目的 App Key。
                appkey= "xxx"
                // 当前登录的用户 ID。
                username= "xxx"
                // 声网 token。
                agoraToken= "xxx"
                />
        </div>
        );
      }
    }
   
    export default App;

2. 设置会话布局。

   打开 my-app/src/App.css，将文件中的内容替换为以下代码：

    /** App.css */
    .container {
        height: 100%;
        width: 100%
    }

测试你的应用

在你的终端中，运行以下命令启动该应用程序：

npm run start

你可以在浏览器中查看应用程序启动。发送消息前，请参考添加好友或加入群组 添加联系人或加入群组。

后续步骤

本节介绍你可以在项目中实现的更高级功能。

自定义属性

EaseChat 提供以下自定义属性。你可以通过设置这些属性实现自定义功能和布局。为确保 EaseChat 的功能实现，必须设置所有必选参数。

添加业务逻辑

在你自己的业务逻辑使用即时通讯 IM UIKit 提供的各种回调事件，如下所示：

1. 获取 SDK 实例

    const WebIM = EaseApp.getSdk({ appkey: 'xxxx' })

2. 添加回调事件

   调用 addEventHandler 添加回调事件。

    // 利用 `nameSpace` 定义不同的业务逻辑，可以根据需求添加多个。
    WebIM.conn.addEventHandler("handlerId", {
     onConnected: () => {},
     onTextMessage: (message) => {},
     // ...
    });

参考

即时通讯 IM 在 GitHub 上提供了一个已集成 UIKit 的开源样本项目 。