实现基本消息收发

---

本文介绍如何使用 ZIM SDK 快速实现基本的单聊会话消息收发功能。

1 前提条件

在使用 ZIM SDK 前，请确保：

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

2 集成 SDK

2.1 （可选）新建项目

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

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

2. 在出现的表单中，选择 “uni-app” 平台，并填写项目名称。

3. 单击“创建”，即可创建项目。

2.2 导入 SDK

以下两种方式可以任选一种导入。

方式一：在 ZEGO 官网下载 SDK

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

2. 将解压缩后的文件夹，直接复制到项目工程根目录下的 “nativeplugins” 文件夹，如果没有该目录，请手动创建。

   

方式二：通过 uni-app 插件市场获取 ZIM uni-app SDK

通过 uni-app 插件市场也有两种方式导入，请任选一种：

• 单击 “购买（0元） for 云打包”，选择相应的项目导入。

• 单击 “下载 for 离线打包”，离线导入。

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

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

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

   

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

   

2.4 自定义调试基座

2.4.1 制作自定义调试基座

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

   

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

   

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

   

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

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

2.5 集成 JS 封装层

2.5.1 导入 JS 封装层

以下两种方式可以任选一种导入。

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

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

  

• 方式二：在插件市场的 Zego ZIM 即时通讯原生插件（JS 封装层） 界面单击右侧的 “使用 HBuilderX 导入插件”。

  

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

  

2.5.2 在项目中引入 JS 封装层

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

import ZIM from './js_sdk/zego-ZIMUniplugin-JS/lib/index.js';

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);
});

// 注册监听“Token 即将过期”的回调
zim.on('tokenWillExpire', function (zim, { second }) {
    console.log('tokenWillExpire', second);
    // 可以在这里调用 renewToken 接口来更新 token
    // 新 token 生成可以参考上文
    zim.renewToken(token)
        .then(function({ token }){
            // 更新成功
        })
        .catch(function(err){
            // 更新失败
        })
});

详细的接口介绍，请参考 connectionStateChanged、receivePeerMessage、tokenWillExpire。

4. 登录 ZIM

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

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

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

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

zim.login(userID, config)
    .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 接口调用时序图如下：

相关文档

• 如何获取 SDK 的日志信息？
• 如何设置消息的优先级更为合理？
• 什么时候使用自定义消息？
• 如何限制只有好友之间才能互发消息？
• 支持发送消息给自己吗？