uniapp即时聊天功能实现(基于即构uniapp 即时通讯SDK实现消息收发)

本文介绍如何使用即构的 uniapp 即时通讯SDK(ZIM SDK)快速实现基本的消息收发功能。ZIM SDK具有登录状态监控、会话模块、房间模块、群组模块、消息模块、消息优先级、历史消息存储、系统消息推送和呼叫邀请等功能。

1 前提条件

在使用 ZIM SDK 前，请确保：

已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台自助开通 ZIM 服务（详情请参考 项目管理 – 即时通讯）

2 集成 SDK

2.1 （可选）新建项目

此步骤以如何创建新项目为例，如果是集成到已有项目，可忽略此步。

启动 HBuilderX，选择“文件 > 新建 > 项目”菜单。

2.2 导入 SDK

在 ZEGO 官网下载 SDK：

1. 请参考 下载 页面，获取最新版本的 SDK 到本地，并将得到的 “zego-ZIMUniPlugin.zip” 文件解压缩。
2. 将解压缩后的文件夹，直接复制到项目工程根目录下的 “nativeplugins” 文件夹，如果没有该目录，请手动创建。

2.3 在 uni-app 项目中导入插件

• 单击项目目录的 “manifest.json” 文件后，单击 “App原生插件配置” 中的 “选择本地插件” 或 “选择云端插件”。

• 在弹出的选择框中，选择 “Zego ZIM 即时通讯 SDK” 后，单击“确认”，即添加成功。

2.4 自定义调试基座

2.4.1 制作自定义调试基座

• 选择 “运行 > 运行到手机或模拟器 > 制作自定义调试基座” 菜单。

• 在弹出的界面中，按照 uni-app 教程，填写相关信息，并单击“打包”进行云打包。

打包成功后，控制台会收到 uni-app 的相关提示。

2.4.2 切换运行基座为自定义调试基座

自定义调试基座，请选择“运行 > 运行到手机或模拟器 > 运行基座选择 > 自定义调试基座”菜单。

2.5 集成 JS 封装层

2.5.1 导入 JS 封装层

请参考 下载 页面，获取最新版本的 JS 封装层到本地，并将得到的 “zego-ZIMUniplugin-JS.zip” 文件解压缩。

下载的 JS 封装层可以拷贝到 HBuilderX 的 “js_sdk” 目录中。（如无该目录，请创建一个）

导入的 JS 封装层将存储在 “js_sdk” 目录中。

2.5.2 在项目中引入 JS 封装层

导入后，可以在业务代码中引入 JS 封装层，并调用 ZIM 相关接口，示例如下：

import ZIM from './js_sdk/zego-ZIMUniPlugin-JS/lib';

3 实现基本收发消息

以下流程中，我们以客户端 A 和 B 的消息交互为例，实现 1v1 聊天功能：

3.1 实现流程

请参考 跑通示例源码 获取源码。

1. 导入 SDK 文件

请参考 2.2 导入 SDK，导入 SDK 文件。

2. 创建 ZIM 实例

首先我们需要在项目中创建 ZIM 实例，一个实例对应的是一个用户，表示一个用户以客户端的身份登录系统。

例如，客户端 A、B 分别调用 create 接口，传入在 1 前提条件 中获取到的 AppID，创建了 A、B 的实例：

// 请注意：ZIM 从 2.3.0 版本开始支持 AppSign 鉴权，SDK 也默认为 AppSign 鉴权，如果您需要切换鉴权方式：
// (1) 2.3.3 及以上版本的 SDK，支持鉴权方式的自主切换; (2) 2.3.0 版本的 SDK，需要切换为 “Token 鉴权” 时，请联系 ZEGO 技术支持处理

// 静态同步方法，创建 zim 实例，传入 AppID 和 AppSign
// create 方法仅第一次调用时会创建 ZIM 实例，后续调用会返回 null。
ZIM.create({ appID: 0, appSign: '' });
// 通过 getInstance 获取单实例，避免热更新导致 create 多次创建返回 null。
var zim = ZIM.getInstance();

3. 监听回调事件

在客户端登录前，开发者可以通过调用 on 接口，自定义 ZIM 中的事件回调，接收到 SDK 异常、消息通知回调等的通知。

// 注册监听“运行时错误信息”的回调  
zim.on('error', function (zim, errorInfo) {
    console.log('error', errorInfo.code, errorInfo.message);
});

// 注册监听“网络连接状态变更”的回调
zim.on('connectionStateChanged', function (zim, { state, event, extendedData }) {
    console.log('connectionStateChanged', state, event, extendedData);
});

// 注册监听“收到单聊消息”的回调
zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
    console.log('receivePeerMessage', messageList, fromConversationID);
});

4. 登录 ZIM

创建实例后，客户端 A 和 B 需要登录 ZIM，只有登录成功后才可以开始发送、接收消息等。

客户端需要使用各自的用户信息进行登录。调用 login 接口，传入用户信息 ZIMUserInfo 对象，进行登录。

// userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// userName 最大 256 字节的字符串，无特殊字符限制。
var userInfo = { userID: 'xxxx', userName: 'xxxx' };

// 登录时：
// 使用 Token 鉴权，需要开发者填入 "使用 Token 鉴权" 文档生成的 Token，详情请参考 [使用 Token 鉴权]
// 使用 AppSign 鉴权 (2.3.0 或以上版本的默认鉴权方式)，Token 参数填空字符串

zim.login(userInfo, '')
    .then(function () {
        // 登录成功
    })
    .catch(function (err) {
        // 登录失败
    });

5. 发送消息

客户端 A 登录成功后，可以向客户端 B 发送消息。

目前 ZIM 支持的消息类型有文本消息、自定义数据类型的信令消息、房间内弹幕文本消息、图片消息、文件消息、语音消息、视频消息和自定义消息。

以下为发送单聊文本消息为例：客户端 A 可以调用 sendMessage 接口，传入客户端 B 的 userID、消息内容、消息类型 conversationType 等参数，即可发送一条文本消息到 B 的客户端。

• ZIMMessageSentResult 回调，判断消息是否发送成功。
• onMessageAttached 回调，在消息发送前，可以获得一个临时的 ZIMMessage，以便您添加一些业务处理逻辑。例如：在发送消息前，获取到该条消息的 ID 信息。开发者在发送“视频”等内容较大的消息时，可以在消息上传完成前，缓存该消息对象，直到收到 SDK 发送成功通知时，通过比较对象相同来实现发送前 Loading 的效果。

// 发送单聊 `Text` 信息

var toConversationID = ''; // 对方 userID
var conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
var config = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中：2，高：3
};

var messageTextObj = { type: 1, message: '文本消息内容', extendedData: '消息的扩展信息（可选）' };
var notification = {
    onMessageAttached: function(message) {
        // todo: Loading
    }
}

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // 发送成功
    })
    .catch(function (err) {
        // 发送失败
    });

6. 接收消息

客户端 B 登录 ZIM 后，将会收到在 on 回调中设置的 receivePeerMessage 监听接口，收到客户端 A 发送过来的消息。

// 注册监听“收到单聊消息”的回调
zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
    console.log('receivePeerMessage', messageList, fromConversationID);
});

7. 退出登录

如果客户端需要退出登录，直接调用 logout 接口即可。

zim.logout();

8. 销毁 ZIM 实例

如果不需要 ZIM 实例，可直接调用 destroy 接口，销毁实例。

zim.destroy();

3.2 API 时序图

通过以上的实现流程描述，API 接口调用时序图如下：