即时通讯
  • iOS
  • Android
  • macOS
  • Windows
  • Web
  • 小程序
  • Flutter
  • Unity3D
  • uni-app
  • React Native : JavaScript
  • 产品简介
  • 下载
  • 快速开始
    • 跑通示例源码
    • 实现基本消息收发
  • 用户相关
  • 房间相关
  • 群组相关
  • 消息相关
  • 呼叫邀请
  • 会话管理
  • 离线推送
  • 常见错误码
  • 服务端 API
  • 客户端 API
  • 常见问题

实现基本消息收发

更新时间:2023-09-01 16:01

本文介绍如何使用 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.3.0 及以上版本的 SDK,开始支持 “AppSign 鉴权”,同时仍支持 “Token 鉴权”,若您需要升级鉴权方式,可参考 ZIM 如何从 AppSign 鉴权升级为 Token 鉴权

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
  1. 编译运行 Android 平台:

    yarn react-native run-android

2.2 导入 SDK

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

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

    npm 下载包支持 typescript 语言(推荐)。

  2. 导入 SDK。

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

3 实现基本收发消息

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

/Pics/ZIM/quick_start_Implementation_Web.png

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

详细的接口介绍,请参考 connectionStateChangedreceivePeerMessagetokenWillExpire

4. 登录 ZIM

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

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

  • “userID”、“userName” 支持开发者自定义规则生成。建议开发者将 “userID” 设置为一个有意义的值,可将其与自己的业务账号系统进行关联。
  • 2.3.0 或以上版本的 SDK,默认鉴权方式为 “AppSign 鉴权”,登录 ZIM 时只需传入 ZIMUserInfo、Token 传入空字符串即可。
  • 如果您使用的是 “Token 鉴权”,请参考 使用 Token 鉴权 文档,获取 Token 后,并在登录 ZIM 时传入 Token,鉴权通过后才能登录成功。
// 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 支持的消息类型如下:

消息类型 说明 特性及适用场景
ZIMTextMessage(1)
文本消息。消息大小不超过 32 KB,单个客户端发送频率限制为 10 次/秒。
消息可靠有序,可存储为历史消息;一般适用于“单聊”、“群聊”等即时聊天的场景和“房间聊天”的公屏聊天场景。房间解散后,“房间聊天”的消息不存储。

相关接口:sendMessage

ZIMCommandMessage(2)
开发者可自定义数据类型的信令消息。消息大小不超过 5 KB,单个客户端发送频率限制为 10 次/秒。
支持更高的并发;一般适用于“语聊房”、“在线课堂”等房间内的信令传输,比如上下麦操作、送礼物,发送在线课堂课件等。

相关接口:sendMessage

ZIMBarrageMessage(20)
房间内弹幕文本消息。消息大小不超过 5 KB,单个客户端发送频率无限制。
专门用于房间内的高频、不可靠、允许丢掉的消息,一般适用于发送“弹幕消息”的场景中。

支持高并发,但不可靠,不保证消息送达。

相关接口:sendMessage

ZIMImageMessage(11)
图片消息。支持主流图片格式,包括 JPG、PNG、BMP、TIFF、GIF、WebP,大小不超过 10 MB,单个客户端发送频率限制为 10 次/秒。
消息可靠有序,可存储为历史消息(默认保存 14 天);一般用于单聊、房间、群聊等即时聊天场景。

相关接口: sendMediaMessage

ZIMFileMessage(12)
文件消息。消息内容为文件,格式不限,大小不超过 100 MB,单个客户端发送频率限制为 10 次/秒。
ZIMAudioMessage(13)
语音消息。支持 MP3、M4A 格式的语音文件,时长不超过 300 秒,大小不超过 6 MB,单个客户端发送频率限制为 10 次/秒。
ZIMVideoMessage(14)
视频消息。支持 MP4、MOV 格式的视频文件,大小不超过 100 MB,单个客户端发送频率限制为 10 次/秒。仅支持视频编码格式为 H264 和 H265 的视频文件在消息发送成功后获取该视频首帧的宽、高信息。
ZIMCustomMessage(200)
自定义消息。开发者可自定义消息的类型,并自行完成消息的解析,ZIM SDK 不负责定义和解析自定义消息的具体内容。
一般可用于发送投票类型、接龙类型、视频卡片类型等消息。

相关接口: sendMessage

以下为发送单聊文本消息为例:客户端 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 接口调用时序图如下:

  • 发送消息时,统一使用 sendMessage 接口,并根据消息类型传入对应的 conversationType 取值。
  • 接收消息时:

相关文档

本篇目录