本文介绍如何使用 ZIM SDK 快速实现基本的消息收发功能。
ZIM SDK 提供了如下接入方案:
在此方案中,您需要通过您自己的业务系统实现以下业务逻辑:
在使用 ZIM SDK 前,请确保:
目前,ZEGO 控制台 仅支持 iOS/Android/macOS/Windows 平台的 ZIM 服务自助开通使用;暂不支持 Web/小程序 平台的服务自助开通。
开发者如需使用 Web/小程序 平台的 SDK,请联系 ZEGO 技术支持,配置相关服务权限。
启动 Xcode,在 “Welcome to Xcode” 窗口中单击 “Create a new Xcode project” 或选择 “File > New > Project” 菜单。在出现的表单中,选择 iOS 平台,并在 “Application” 下选择 “App”。
填写表单并选取各个选项来配置项目,完成后,单击 “Next”。
必须提供 “Product Name” 和 “Organization Identifier”,用于创建 App 的唯一标识 “Bundle Identifier”。
选择项目存储路径,单击 “Create” 创建项目。
开发者可通过以下任意一种方式实现集成 SDK。
安装 CocoaPods,安装时的常见问题请参考 CocoaPods 常见问题 - 安装 CocoaPods。
打开终端,进入项目根目录,执行 pod init
命令创建 Podfile 文件。
打开 Podfile 文件,在 “target” 下添加 pod 'ZIM'
,需要将 “MyProject” 替换为开发者的 Target 名称。
由于 SDK 为 XCFramework,只有 1.10.0 或以上版本的 CocoaPods 才能集成该 SDK。
target 'MyProject' do
use_frameworks!
pod 'ZIM'
end
执行 pod repo update
命令更新本地索引,确保能安装最新版本的 SDK,最新版本号请参考 发布日志。
执行 pod install
命令安装 SDK。
请参考 下载 SDK,下载最新版本的 SDK。
将 SDK 包解压至项目目录下,例如 “libs” 文件夹下。
选择 “TARGETS > General > Frameworks,Libraries,and Embedded Content” 菜单,添加 “ZIM.xcframework”,将 “Embed” 设置为 “Embed & Sign”。
以下流程中,我们以客户端 A 和 B 的消息交互为例:
请参考 跑通示例源码 获取源码,相关功能的源码请查看 “ZIMExampleLegacy/Peer/ZGPeerChatViewController.m” 的文件。
在项目文件中引入头文件 “ZIM.h”。
#import "ZIM/ZIM.h"
首先我们需要在 SDK 中创建 ZIM 实例,一个实例对应的是一个用户,表示一个用户以客户端的身份登录系统。
例如,客户端 A、B 分别调用 create 接口,传入在 2 前提条件 中获取到的 AppID,创建了 A、B 的实例:
// 创建
// 创建 ZIM 对象,传入 APPID
ZIM *zim = [ZIM createWithAppID:(unsigned int)appID];
// 将 (unsigned int)appID 替换为您申请的AppID
由于大多数开发者,在整个流程中,只需要将 ZIM 实例化一次,因此 ZEGO 建议您将 ZIM 单例化并保存。
创建一个 ZGZIMManager 类,在该类中声明并实现了一个 “shared” 类方法,该方法将会在首次调用时创建并返回一个 ZGZIMManager 的对象,在该对象中实例化 ZIM 并保存,此后在项目的任意位置导入 ZIMManager.h 头文件,调用 “[ZGZIMManager shared].zim” 将会返回 zim 对象。
#import <Foundation/Foundation.h>
#import "ZIM/ZIM.h"
NS_ASSUME_NONNULL_BEGIN
@interface ZGZIMManager : NSObject
@property (nonatomic, strong) ZIM *zim;
+ (ZGZIMManager *)shared;
@end
NS_ASSUME_NONNULL_END
#import "ZGZIMManager.h"
static ZGZIMManager *_sharedManager = nil;
@interface ZGZIMManager ()
@end
@implementation ZGZIMManager
+ (ZGZIMManager *)shared {
if (!_sharedManager) {
@synchronized (self) {
if (!_sharedManager) {
_sharedManager = [[self alloc] init];
_sharedManager.zim = [ZIM createWithAppID:123]; //将此处 123 替换成自己的 APPID
}
}
}
return _sharedManager;
}
@end
在客户端登录前,开发者需要先声明 ZIMEventHandler
协议,然后通过调用 setEventHandler 接口并实现协议中的各个方法,来设置自定义 ZIM 中的事件回调,接收到 SDK 异常、消息通知回调等的通知。
下图以在 ViewContorller 文件中,设置自定义连接状态改变为例。
[zim setEventHandler:self];
- (void)zim:(ZIM *)zim errorInfo:(ZIMError *)errorInfo{
// 接收错误码的回调,通过该回调可以收到 sdk 的通用错误码。
}
- (void)zim:(ZIM *)zim tokenWillExpire:(unsigned int)second{
// 用于提示 token 即将过期,开发者可以通过该回调监听 token 快要过期的通知,自定义应对这一事件的 UI 状态
}
- (void)zim:(ZIM *)zim connectionStateChanged:(ZIMConnectionState)state event:(ZIMConnectionEvent)event extendedData:(NSDictionary *)extendedData {
// 连接状态变化通知,开发者可以通过该回调监听当前的登录连接状态,展示对应的 UI 状态
}
- (void)zim:(ZIM *)zim receivePeerMessage:(NSArray<ZIMMessage *> *)messageList fromUserID:(NSString *)fromUserID {
// 接收 1v1 通信的消息回调,登录后可通过该回调接收 1v1 通信的消息
}
- (void)zim:(ZIM *)zim
receiveRoomMessage:(NSArray<ZIMMessage *> *)messageList
fromRoomID:(NSString *)fromRoomID{
// 接收房间消息回调,登录并进入房间后可通过该回调接收房间消息
}
- (void)zim:(ZIM *)zim
roomMemberJoined:(NSArray<ZIMUserInfo *> *)memberList
roomID:(NSString *)roomID{
// 接收房间成员加入回调,登录并进入房间后可以通过该回调收到房间成员进入的消息
}
- (void)zim:(ZIM *)zim
roomMemberLeft:(NSArray<ZIMUserInfo *> *)memberList
roomID:(NSString *)roomID{
// 接收房间成员退出回调,登录并进入房间后可以通过该回调收到房间成员退出房间的消息
}
详细的接口介绍,请参考 tokenWillExpire、connectionStateChanged、receivePeerMessage、receiveRoomMessage、roomMemberJoined、roomMemberLeft。
创建实例后,客户端 A 和 B 需要登录 ZIM,只有登录成功后才可以开始发送、接收消息、更新 Token 等。
客户端需要使用各自的用户信息和 Token 进行登录。调用 loginWithUserInfo 接口进行登录,传入用户信息 ZIMUserInfo 对象,以及在 2 前提条件 中获取到的 Token 进行鉴权,鉴权通过后才能登录成功。
首先创建客户端的用户个人信息对象 ZIMUserInfo;创建完毕后,客户端可以调用 loginWithUserInfo 接口登录 ZIM。
// userID 和 userName,最大 32 字节的字符串。仅支持数字,英文字符 和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '/', '\'。
ZIMUserInfo *userInfo = [[ZIMUserInfo alloc]init];
userInfo.userID = @"zegoUser1"; //填入NSString类型的值
userInfo.userName = @"zegotest";//填入NSString类型的值
// 登录时,需要开发者 按照 "使用 Token 鉴权" 文档生成 token 即可
[zim loginWithUserInfo:userInfo token:token callback:^(ZIMError * _Nonnull errorInfo) {
//这里填写登录的回调
}];
客户端 A 登录成功后,可以向客户端 B 发送消息。
目前 ZIM 支持的消息类型如下:
消息类型 | 说明 | 特性及适用场景 |
---|---|---|
ZIMTextMessage(1) |
文本消息。消息大小不超过 32 KB,单个客户端发送频率限制为 10 次/秒。 |
消息可靠有序,可存储为历史消息;一般适用于“单聊”、“群聊”等即时聊天的场景。 |
ZIMCommandMessage(2) |
开发者可自定义数据类型的信令消息。消息大小不超过 5 KB,单个客户端发送频率限制为 10 次/秒。 |
支持更高的并发;一般适用于“语聊房”、“在线课堂”等房间内的即时聊天;房间解散后,消息不保存。 |
ZIMBarrageMessage(20) |
房间内弹幕文本消息。消息大小不超过 5 KB,单个客户端发送频率无限制。 |
专门用于房间内的高频、不可靠、允许丢掉的消息,一般适用于发送“弹幕消息”的场景中。 支持高并发,但不可靠,不保证消息送达。 |
ZIMImageMessage(11) |
图片消息。支持主流图片格式,包括 JPG、PNG、BMP、TIFF、GIF,大小不超过 10 MB,单个客户端发送频率限制为 10 次/秒。 |
消息可靠有序,可存储为历史消息;一般用于单聊、房间、群聊等即时聊天场景。 |
ZIMFileMessage(12) |
文件消息。消息内容为文件,格式不限,大小不超过 100 MB,单个客户端发送频率限制为 10 次/秒。 |
|
ZIMAudioMessage(13) |
语音消息。支持 MP3 格式的语音文件,时长不超过 300 秒,大小不超过 6 MB,单个客户端发送频率限制为 10 次/秒。 |
|
ZIMVideoMessage(14) |
视频消息。支持 MP4 或 MOV 格式的视频文件,大小不超过 100 MB,单个客户端发送频率限制为 10 次/秒。 |
客户端 A 可以调用 sendPeerMessage 接口,传入客户端 B 的 userID、消息内容等信息,即可发送一条消息到 B 的客户端,同时可以通过 ZIMMessageSentCallback 接口的回调信息,判断消息是否发送成功。
// 发送单聊信息
ZIMTextMessage *zimMessage = [[ZIMTextMessage alloc]init];
zimMessage.message = @"消息内容";
ZIMMessageSendConfig *config = [[ZIMMessageSendConfig alloc] init];
config.priority = ZIMMessagePriorityMedium; // 消息优先级,取值为 低:1 默认,中:2,高:3
[zim sendPeerMessage:zimMessage toUserID:userID config:config callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
//这里写发送消息后的回调
//toUserID填这条消息接收者的 userID
}];
客户端 B 登录 ZIM 后,将会收到在 setEventHandler 回调中设置的 receivePeerMessage 监听接口,收到客户端 A 发送过来的消息。
收到消息时,由于类型是基类,首先需要判断消息类型是 Text 还是 Command,开发者需要强转基类为具体的子类,然后从 message 字段获取消息内容。
- (void)zim:(ZIM *)zim
receivePeerMessage:(NSArray<ZIMMessage *> *)messageList
fromUserID:(NSString *)fromUserID{
for(ZIMMessage *message in messageList){
if (message.type == ZIMMessageTypeText){
ZIMTextMessage *textMessage = (ZIMTextMessage *)message;
}
else if (message.type == ZIMMessageTypeCustom){
ZIMCustomMessage *customMessage = (ZIMCustomMessage *)message;
}
}
}
如果客户端需要退出登录,直接调用 logout 接口即可。
[zim logout];
如果不需要 ZIM 实例,可直接调用 destroy 接口,销毁实例。
[zim destroy];
通过以上的实现流程描述,API 接口调用时序图如下:
联系我们
文档反馈