logo
当前页

实现基本消息收发


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

说明

uni-app SDK 是一个基于原生 iOS/Android 平台 ZIM SDK 的 uni-app Wrapper。开发者如需使用 uni-app 开发 Web 或小程序平台的应用,请下载对应的 SDK 集成使用:下载 Web SDK下载小程序 SDK

1 前提条件

在使用 ZIM SDK 前,请确保:

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

2 集成 SDK

2.1 (可选)新建项目

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 制作自定义调试基座

说明

uni-app 官方自定义调试基座使用说明,请参考 什么是自定义调试基座及使用说明

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

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

    打包成功后,控制台会收到 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 相关接口,示例如下:

Untitled
import ZIM from './js_sdk/zego-ZIMUniplugin-JS/lib/index.js';
1
Copied!

3 实现基本收发消息

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

3.1 实现流程

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

1. 导入 SDK 文件

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

2. 创建 ZIM 实例

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

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

Untitled
// 请注意: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();
1
Copied!

3. 监听回调事件

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

Untitled
// 注册监听“运行时错误信息”的回调  
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('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log('peerMessageReceived', messageList, info, fromConversationID);
});

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

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

4. 登录 ZIM

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

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

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

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 次/秒。

消息可靠有序,可存储为历史消息(保存时间请参考 计费说明 - 版本说明 中“历史消息存储天数”。); 一般用于单聊、房间、群聊等即时聊天场景。

相关接口: sendMediaMessage

ZIMFileMessage(12)文件消息。消息内容为文件,格式不限,大小不超过 100 MB,单个客户端发送频率限制为 10 次/秒。
ZIMAudioMessage(13)语音消息。支持 MP3、M4A 格式的语音文件,时长不超过 300 秒,大小不超过 6 MB,单个客户端发送频率限制为 10 次/秒。
ZIMVideoMessage(14)视频消息。支持 MP4、MOV 格式的视频文件,大小不超过 100 MB,单个客户端发送频率限制为 10 次/秒。仅支持视频编码格式为 H264 和 H265 的视频文件在消息发送成功后获取该视频首帧的宽、高信息。
ZIMCombineMessage(100)合并消息,消息大小无限制,单个客户端发送频率限制为 10 次/秒。

消息可靠有序,可存储为历史消息(保存时间请参考 计费说明 - 版本说明 中“历史消息存储天数”。); 一般用于单聊、房间、群聊等即时聊天场景。

相关接口:sendMessage

ZIMCustomMessage(200)自定义消息。开发者可自定义消息的类型,并自行完成消息的解析,ZIM SDK 不负责定义和解析自定义消息的具体内容。

消息可靠有序,可存储为历史消息(保存时间请参考 计费说明 - 版本说明 中“历史消息存储天数”。); 一般可用于发送投票类型、接龙类型、视频卡片类型等消息。

相关接口: sendMessage

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

  • ZIMMessageSentResult 回调,判断消息是否发送成功。
  • onMessageAttached 回调,在消息发送前,可以获得一个临时的 ZIMMessage,以便您添加一些业务处理逻辑。例如:在发送消息前,获取到该条消息的 ID 信息。开发者在发送“视频”等内容较大的消息时,可以在消息上传完成前,缓存该消息对象,直到收到 SDK 发送成功通知时,通过比较对象相同来实现发送前 Loading 的效果。
Untitled
// 发送单聊 `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) {
        // 发送失败
    });
1
Copied!

6. 接收消息

客户端 B 登录 ZIM 后,将会收到在 on 回调中设置的 [peerMessageReceived](@ peerMessageReceived) 监听接口,收到客户端 A 发送过来的消息。

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

7. 退出登录

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

Untitled
zim.logout();
1
Copied!

8. 销毁 ZIM 实例

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

Untitled
zim.destroy();
1
Copied!

3.2 API 时序图

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

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

相关文档

Previous

跑通示例代码

Next

使用 Token 鉴权