实现基本消息收发

---

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

1 前提条件

在使用 ZIM SDK 前，请确保：

• 开发环境：

  • React Native 0.60.0 或以上版本。
  • iOS 11.0 或以上版本的 iOS 设备或模拟器（推荐使用真机）。
  • Android 4.0.3 或以上版本的 Android 设备或模拟器（推荐使用真机），如果为真机，请开启“允许调试”选项。
  • iOS / Android 设备已经连接到 Internet。
  • 配置 VS Code 开发环境，可在应用商店中搜索 “React Native Tools” 扩展并下载。

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

2 集成 SDK

2.1 （可选）新建项目

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

1. 使用 React Native 内置的命令行工具，创建一个名为 “zego-zim-example” 的新项目。

   此命令行工具不需要安装，可以直接用 node 自带的 npx 命令来使用：

   npx react-native init zego-zim-example

2. 编译运行 iOS 平台：

   yarn react-native run-ios

3. 编译运行 Android 平台：

   yarn react-native run-android

2.2 导入 SDK

开发者可以使用 npm 获取 SDK。

1. 执行 npm i zego-zim-react-native 或 yarn add zego-zim-react-native 命令安装依赖。

2. 导入 SDK。

   import ZIM from 'zego-zim-react-native';

3. 进入 iOS 根目录，并执行 pod install 命令安装依赖。

完成如上操作即可在项目中通过 javascript 或 typescript (推荐) 来使用 zego-zim-react-native SDK。

3 实现基本收发消息

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

3.1 实现流程

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

1. 导入 SDK 文件

请参考 2.2 导入 SDK，使用 npm 获取 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 的日志信息？
• 如何设置消息的优先级更为合理？
• 什么时候使用自定义消息？
• 如何限制只有好友之间才能互发消息？
• 支持发送消息给自己吗？