本文介绍如何使用 ZIM SDK 快速实现基本的单聊会话消息收发功能。
本文档适用于开发以下平台应用:iOS、Android、macOS、Windows。
请确保开发环境满足以下技术要求:
安装 Unity 2021.3.18f1c1 或以上版本。若未安装,可以在 Unity 官网 下载 Unity Hub,然后安装您需要的 Unity 版本(若不清楚,建议您安装最新的 LTS 版本)。下载时,推荐根据自身需要运行到的平台,勾选对应的 Plaforms 模块一起下载,以在 Windows 上安装为例:
根据示例代码需要运行到的平台,选择对应的开发环境或设备:
SDK 同时也支持 Token 鉴权,若您需要升级鉴权方式,可参考 如何从 AppSign 鉴权升级为 Token 鉴权。
单击 “新建” 按钮,选择 “3D” 模版,填写 “项目名称”,选择 “位置” 存放项目,单击 “创建” 按钮创建项目。
下载 并解压 SDK 压缩包,将 解压后的 ZIMUnity3D 目录下的 “ZIM” 文件夹到拷贝到开发者项目的 "Assets" 目录下,即可集成 SDK :
对于不同的运行平台,需要做一些额外处理。
Unity 项目中不能存在同名的 .dll 文件,否则在 Build 时会出现 “Multiple plugins with the same name 'zim'” 错误。开发者需根据实际业务情况删除 “Plugins/Windows” 文件夹下的 x64 文件夹或 x86 文件夹。
如果不准备在 Windows 平台上运行示例源码,开发者可以直接删除 “Plugins/Windows” 文件夹。
如果 Unity 为 2019.3 或之前版本,由于其不支持将 macOS dylib 作为 Plugins,请将 "libZIM.dylib" 重命名为 "libZIM.bundle",以便正确导入 SDK。此外,macOS 应为 10.5 或以上版本。
如下图所示,在路径“ZIM/Plugins/IOS/XCFramework”下有三个文件夹:
说明如下:
文件夹名称 | 作用 | 相关操作 |
---|---|---|
ios-arm64_armv7 | 真机架构,用于真机运行调试以及上架发布。 | 需要在真机上运行时,请保留此文件夹并删除其他文件夹。 |
ios-arm64_x86_64-simulator | 模拟器架构,用于模拟器运行调试。 | 需要在 iOS 模拟器上运行时,请保留此文件夹并删除其他文件夹。(即当工程配置 iOS Target SDK 指定为 Simulator SDK 时。) |
ios-arm64_x86_64-maccatalyst | iOS MacCatalyst 架构。 | 目前 Unity 暂不支持此架构,请直接删除。 |
构建 Android App 时也可能会提示存在多个 Windows dll 文件。请按照上述 Windows 的处理方式解决。
以下流程中,我们以客户端 A 和 B 的消息交互为例:
在项目文件中引入头文件。
using ZEGO;
首先我们需要在 SDK 中创建 ZIM 单实例,实例对应的是一个用户,表示一个用户以客户端的身份登录系统。
例如,客户端 A、B 分别调用 Create 接口,传入在 前提条件 中获取到的 AppID、AppSign(开发 Web 平台应用时无需使用 “appsign”,为防止暴露,请勿传入),创建了 A、B 的实例:
// 创建
// 通过插件创建 ZIM 单实例,传入 APPID、AppSign
// 请注意:ZIM 从 2.3.0 版本开始支持 AppSign 鉴权,SDK 也默认为 AppSign 鉴权,如果您需要切换鉴权方式:
// (1) 2.3.3 及以上版本的 SDK,支持鉴权方式的自主切换; (2) 2.3.0 版本的 SDK,需要切换为 “Token 鉴权” 时,请联系 ZEGO 技术支持处理
//定义唯一 ZIM 实例(实际使用时一般全局定义)
ZIM zim;
ZIMAppConfig config = new ZIMAppConfig();
config.appID = (uint)appID; // 请通过 [ZEGO 控制台](https://console.zego.im/) 获取,格式为 123456789,详情请参考控制台的 [项目信息](https://doc-zh.zego.im/article/12107)
config.appSign = (string)appSign;// 请通过 [ZEGO 控制台](https://console.zego.im/) 获取,格式为"0123456789012345678901234567890123456789012345678901234567890123",64 个字符,详情请参考控制台的 [项目信息](https://doc-zh.zego.im/article/12107)
zim = ZIM.Create(config);
在调用登录接口前,开发者必须注册所需回调。
void SetZIMEventHandler()
{
// SDK 出现异常时,会通过该回调提示详细的异常信息。
ZIM.GetInstance().onError = (ZIM zim, ZIMError errorInfo) => {};
// 连接状态发生改变时会通过该回调将目前的状态与事件通知用户。
ZIM.GetInstance().onConnectionStateChanged = (ZIM zim, ZIMConnectionState state,
ZIMConnectionEvent connectionEvent,
Dictionary<string,string> extendedData) => {};
// 当收到此回调时,开发者应当及时调用 [RenewToken] 函数更新 Token。
ZIM.GetInstance().onTokenWillExpire = (ZIM zim, uint second) => {};
// 当收到其他人发来的点对点消息时,将会收到此回调。
ZIM.GetInstance().onReceivePeerMessage = (ZIM zim,
List<ZIMMessage> messageList,
string fromUserID) => {};
}
详细的接口介绍,请参考 OnConnectionStateChanged、OnTokenWillExpire、OnReceivePeerMessage。
创建实例后,客户端 A 和 B 需要登录 ZIM,只有登录成功后才可以开始发送、接收消息等。
客户端需要使用各自的用户信息进行登录。调用 Login 接口,传入用户信息 ZIMUserInfo 对象,进行登录。
2.3.0
或以上版本的 SDK,默认鉴权方式为 “AppSign 鉴权”,登录 ZIM 时只需传入 ZIMUserInfo、Token 传入空字符串即可。// userID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// userName 最大 256 字节的字符串,无特殊字符限制。
ZIMUserInfo userInfo = new ZIMUserInfo();
userInfo.userID = "xxxxx";
userInfo.userName = "xxxxx";
// 登录:
// 使用 Token 鉴权,需要开发者填入 "使用 Token 鉴权" 文档生成的 Token,详情请参考 [使用 Token 鉴权]
// 使用 AppSign 鉴权 (2.3.0 或以上版本的默认鉴权方式),Token 参数填空字符串
ZIM.GetInstance().Login(userInfo, "", (ZIMError errorInfo) =>
{
if(errorInfo.code == ZIMErrorCode.Success)
{
//发送成功
}
else
{
//发送失败
}
});
客户端 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 的视频文件在消息发送成功后获取该视频首帧的宽、高信息。 |
以下为发送单聊文本消息
为例:客户端 A 可以调用 SendMessage 接口,传入客户端 B 的 userID、消息内容、消息类型 conversationType 等参数,即可发送一条文本消息
到 B 的客户端。
// // 以下以发送单聊信息为例,conversationType 设置为 ZIMConversationType.Peer
息
string toConversationID = ""; // 对方 userID
ZIMConversationType type = ZIMConversationType.Peer; // 会话类型为 ZIMConversationType.Peer
ZIMTextMessage message = new ZIMTextMessage("文本消息内容");
ZIMMessageSendConfig messageSendConfig = new ZIMMessageSendConfig(); // 使用默认配置
ZIMMessageSendNotification notification = new ZIMMessageSendNotification(); // 消息信息
ZIM.GetInstance().SendMessage(message, toConversationID, type,
messageSendConfig, notification, (ZIMMessage callbackMessage, ZIMError errorInfo) =>
{
if(errorInfo.code == ZIMErrorCode.Success)
{
//发送成功
}
else
{
//发送失败
}
});
客户端 B 登录 ZIM 后,将会通过前面 “3.注册用于接收通知的回调” 中的 OnReceivePeerMessage 接收到消息。
// 注册监听“收到单聊消息”的回调
ZIM.GetInstance().onReceivePeerMessage = (ZIM zim,
List<ZIMMessage> messageList,
string fromUserID) =>
{
//messageList即是收到的单聊消息
};
如果客户端需要退出登录,直接调用 Logout 接口即可。
ZIM.GetInstance().Logout();
如果不需要 ZIM 实例,可直接调用 Destroy 接口,销毁实例。
ZIM.GetInstance().Destroy();
通过以上的实现流程描述,API 接口调用时序图如下:
联系我们
文档反馈