BIMSdk iOS 接入文档

本文档面向首次接入 BIMSdk 的 iOS 开发者，目标是“最快跑通 + 明确规范 + 可落地排错”。

适用范围：BIMSdk iOS（Objective-C / Swift），当前为统一接入版。

1. 接入前置与环境要求

1.1 软硬件要求

最低系统版本：iOS 13.4+
Xcode 版本：Xcode 16+
Swift/Objective-C：均支持

1.2 账号与权限

需要从 BIM 平台申请 AppId 与 BaseURL
JWT 由接入方后台与 BIM 后台交互获取并下发给客户端

2. 集成方式

完整的 CocoaPods、手动 xcframework、依赖版本、升级步骤和 SwiftPM 支持状态，请先阅读安装与升级。

2.1 CocoaPods（推荐）

ruby

# Podfile
pod 'BIMSdk', '1.0.7'

# 如需实时音视频，改为：
# pod 'BIMSdk/Call', '1.0.7'

安装：

bash

pod install

2.2 xcframework（手动集成）

将 BIMSdk.xcframework 添加到工程
额外提供 FMDB 2.7.12 与 Protobuf 3.29.5 对应的动态 Framework
在 Frameworks, Libraries, and Embedded Content 中将上述 Framework 设置为 Embed & Sign
底层 IMSdk 已静态封装进 BIMSdk，不需要额外添加
代码引入：

objc

#import <BIMSdk/BIMSdk.h>

swift

import BIMSdk

BIMSdk 1.0.7 暂未发布 Swift Package，不要把 CocoaPods ZIP 直接当作 SPM 产品使用。

3. 快速开始（5 分钟跑通）

目标：完成“初始化 -> 登录 -> 拉取会话 -> 发送消息”。

需要接入即时呼或会议时，请在完成初始化和登录后继续阅读音视频接入总览。

近期新增能力可直接从以下入口进入：

3.1 初始化

objc

BIMSDKConfig *config = [BIMSDKConfig new];
config.baseURL = @"https://example.com";       // 替换为实际 BaseURL
config.imEndpoint = @"example.com:8029";       // 替换为实际 IMEndPoint
config.logLevel = BIM_LOG_ALL;

[[BIMManager sharedInstance] initSDK:@"yourAppId" config:config];
[[BIMManager sharedInstance] addSDKListener:self];

swift

let config = BIMSDKConfig()
config.baseURL = "https://example.com"
config.imEndpoint = "example.com:8029"
config.logLevel = .LOG_ALL

BIMManager.sharedInstance().initSDK("yourAppId", config: config)
BIMManager.sharedInstance().addSDKListener(listener: self)

3.2 登录

objc

NSString *userId = @"user01";
NSString *jwt = @"<server-issued-jwt>";
[[BIMManager sharedInstance] login:userId jwt:jwt succ:^{
    // 登录成功
} fail:^(int code, NSString *desc) {
    // 登录失败
}];

swift

let userId = "user01"
let jwt = "<server-issued-jwt>"
BIMManager.sharedInstance().login(userId, jwt: jwt) {
    // 登录成功
} fail: { code, desc in
    // 登录失败
}

3.3 获取会话列表

objc

[[BIMManager sharedInstance] getConversationListWithSucc:^(NSArray<BIMConversation *> *conversations) {
    // 会话列表
} fail:^(int code, NSString *desc) {
}];

swift

BIMManager.sharedInstance().getConversationList { conversations in
    // 会话列表
} fail: { code, desc in
}

3.4 进入会话并发送消息

objc

BIMConversation *conversation = ...; // 来自会话列表
BIMTextMessage *msg = [[BIMManager sharedInstance] createTextMessage:@"hello" atAll:NO at:@[]];

[[BIMManager sharedInstance] sendMessage:msg
                                      to:conversation
                                assemble:^{
                                    // 消息已组装，可先渲染到界面
                                }
                                progress:nil
                                    succ:^{
                                        // 发送成功
                                    }
                                    fail:^(int code, NSString *desc) {
                                        // 发送失败
                                    }];

swift

let conversation: BIMConversation = ...
let msg = BIMManager.sharedInstance().createTextMessage("hello", atAll: false, at: [])

BIMManager.sharedInstance().send(msg,
                                 to: conversation,
                                 assemble: {
                                     // 消息已组装，可先渲染到界面
                                 },
                                 progress: nil) {
    // 发送成功
} fail: { code, desc in
    // 发送失败
}

4. 鉴权与登录说明

4.1 JWT 获取与登录

JWT 由接入方后台获取并下发给客户端
客户端只需调用 SDK 登录接口，无需关注内部 token 交换细节

4.2 登录状态与多端登录

当前 SDK 登录状态枚举（BIMLoginStatus）：

BIM_STATUS_LOGINED
BIM_STATUS_LOGINING
BIM_STATUS_LOGOUT

多端登录策略请按服务端配置执行（互踢/共存）。

4.3 退出登录

objc

[[BIMManager sharedInstance] logout:^{
    // 退出成功
} fail:^(int code, NSString *desc) {
}];

swift

BIMManager.sharedInstance().logout {
    // 退出成功
} fail: { code, desc in
}

5. 消息与会话

5.1 消息类型与限制

文本 / 图片 / 文件 / 语音 / 视频 / 自定义消息
FACE 自定义表情 / LOC 地理位置 / 合并聊天记录消息
媒体类文件大小限制：100MB（文件消息上传上限）

扩展消息的创建、资源映射与详情下载见消息 API。

5.2 拉取历史消息

objc

BIMMessageListGetOption *option = [BIMMessageListGetOption new];
option.conversation = conversation;
option.getType = BIMMessageGetTypeOlder;
option.count = 50;
option.anchorMessage = nil;

[[BIMManager sharedInstance] getHistoryMessageList:option
                                              succ:^(NSArray<BIMMessage *> *messages) {
} fail:^(int code, NSString *desc) {
}];

swift

let option = BIMMessageListGetOption()
option.conversation = conversation
option.getType = .older
option.count = 50
option.anchorMessage = nil

BIMManager.sharedInstance().getHistoryMessageList(option) { messages in
} fail: { code, desc in
}

5.3 发送图片/文件/语音/视频

objc

BIMImageMessage *img = [[BIMManager sharedInstance] createImageMessage:path];
[[BIMManager sharedInstance] sendMessage:img
                                      to:conversation
                                assemble:^{}
                                progress:^(double progress) {
                                    // 上传进度
                                }
                                    succ:^{}
                                    fail:^(int code, NSString *desc) {
                                    }];

swift

let img = BIMManager.sharedInstance().createImageMessage(path)
BIMManager.sharedInstance().send(img,
                                 to: conversation,
                                 assemble: {},
                                 progress: { progress in
                                     // 上传进度
                                 }) {
} fail: { code, desc in
}

5.4 会话设置

objc

[[BIMManager sharedInstance] updateConversationSetting:conversation
                                               setting:conversation.setting
                                                  succ:^{}
                                                  fail:^(int code, NSString *desc) {
                                                  }];

swift

BIMManager.sharedInstance().updateConversationSetting(conversation,
                                                      setting: conversation.setting) {
} fail: { code, desc in
}

5.5 自定义消息

objc

NSData *content = [NSJSONSerialization dataWithJSONObject:@{@"type": @"order", @"title": @"订单状态变更"}
                                                   options:0
                                                     error:nil];
BIMCustomMessage *message = [[BIMManager sharedInstance] createCustomMessage:content desc:@"订单状态变更"];

swift

let payload: [String: Any] = ["type": "order", "title": "订单状态变更"]
let data = try JSONSerialization.data(withJSONObject: payload)
let message = BIMManager.sharedInstance().createCustomMessage(data, desc: "订单状态变更")

5.6 APNS 推送

objc

BIMAPNSConfig *apnsConfig = [BIMAPNSConfig new];
apnsConfig.token = deviceToken;
[[BIMManager sharedInstance] setAPNS:apnsConfig succ:^{
} fail:^(int code, NSString *desc) {
}];

swift

let apnsConfig = BIMAPNSConfig()
apnsConfig.token = deviceToken
BIMManager.sharedInstance().setAPNS(apnsConfig) {
} fail: { code, desc in
}

6. 好友与群组（简版）

6.1 好友申请

objc

[[BIMManager sharedInstance] applyFriend:@"targetUserId"
                                   intro:@"你好"
                                    succ:^{}
                                    fail:^(int code, NSString *desc) {
                                    }];

swift

BIMManager.sharedInstance().applyFriend("targetUserId", intro: "你好") {
} fail: { code, desc in
}

6.2 创建群组

objc

BIMDiscussionMember *m1 = [[BIMDiscussionMember alloc] initWithMemberId:@"u001" name:@"Tom" avatar:nil];
BIMDiscussionMember *m2 = [[BIMDiscussionMember alloc] initWithMemberId:@"u002" name:@"Jerry" avatar:nil];
NSArray *members = @[m1, m2];

[[BIMManager sharedInstance] createDiscussionWithName:@"群名称"
                                               avatar:nil
                                                intro:nil
                                               notice:nil
                                              members:members
                                                 succ:^(BIMDiscussion *discussion) {
                                                 }
                                                 fail:^(int code, NSString *desc) {
                                                 }];

swift

let members = [
    BIMDiscussionMember(memberId: "u001", name: "Tom", avatar: nil),
    BIMDiscussionMember(memberId: "u002", name: "Jerry", avatar: nil)
]

BIMManager.sharedInstance().createDiscussion(withName: "群名称",
                                             avatar: nil,
                                             intro: nil,
                                             notice: nil,
                                             members: members,
                                             succ: { discussion in
                                             },
                                             fail: { code, desc in
                                             })

7. 回调监听

7.1 连接状态监听

objc

[[BIMManager sharedInstance] addSDKListener:self];

swift

BIMManager.sharedInstance().addSDKListener(listener: self)

常见回调：

onConnecting
onConnected
onConnectFailed:desc:
onKickedOffline

7.2 消息监听（BIMMsgListener）

注册监听：

objc

[[BIMManager sharedInstance] addMsgListener:self];

swift

BIMManager.sharedInstance().addMsgListener(listener: self)

回调方法：

- (void)onReceiveNewMessage:(BIMMessage *)message;：收到新消息
- (void)onReceiveMessageReadReceipt:(BIMReadMessage *)readMessage;：收到已读回执
- (void)onReceiveMessageRevoked:(BIMUndoMessage *)undoMessage;：收到撤回通知

7.3 会话监听（BIMConversationListener）

注册监听：

objc

[[BIMManager sharedInstance] addConversationListener:self];

swift

BIMManager.sharedInstance().addConversationListener(listener: self)

回调方法：

- (void)onConversationSyncStart;：会话同步开始
- (void)onConversationSyncFinish;：会话同步完成
- (void)onNewConversation:(NSArray<BIMConversation *> *)conversations;：新增会话
- (void)onConversationChanged:(NSArray<BIMConversation *> *)conversations;：会话更新
- (void)onConversationDeleted:(NSArray<NSString *> *)conversationIDList;：会话删除

7.4 群组监听（BIMDiscussionListener）

注册监听：

objc

[[BIMManager sharedInstance] addDiscussionListener:self];

swift

BIMManager.sharedInstance().addDiscussionListener(listener: self)

回调方法：

- (void)onMemberEnter:(NSString * _Nullable)discussionID memberList:(NSArray<BIMDiscussionMember *>*)memberList;：有成员加入群
- (void)onMemberLeave:(NSString * _Nullable)discussionID member:(BIMDiscussionMember *)member;：有成员离开群
- (void)onMemberInvited:(NSString * _Nullable)discussionID opUser:(BIMDiscussionMember *)opUser memberList:(NSArray<BIMDiscussionMember *>*)memberList;：有成员被邀请入群
- (void)onMemberKicked:(NSString * _Nullable)discussionID opUser:(BIMDiscussionMember *)opUser memberList:(NSArray<BIMDiscussionMember *>*)memberList;：有成员被移出群
- (void)onDiscussionMemberMuteChanged:(NSString * _Nullable)discussionID memberList:(NSArray<BIMDiscussionMember *> *)memberList;：群成员禁言状态变更，成员的 muteUntil 表示禁言截止时间
- (void)onDiscussionCreated:(NSString * _Nullable)discussionID;：群创建通知（多端同步场景）
- (void)onDiscussionDismissed:(NSString * _Nullable)discussionID opUser:(BIMDiscussionMember *)opUser;：群解散通知
- (void)onAllDiscussionMembersMuted:(NSString * _Nullable)discussionID isMuted:(BOOL)isMuted muteUntil:(long long)muteUntil;：群全部禁言状态变更
- (void)onQuitFromDiscussion:(NSString * _Nullable)discussionID;：自己退出群通知（多端同步）

7.5 页面销毁时移除监听（建议）

objc

[[BIMManager sharedInstance] removeMsgListener:self];
[[BIMManager sharedInstance] removeConversationListener:self];
[[BIMManager sharedInstance] removeDiscussionListener:self];
[[BIMManager sharedInstance] removeSDKListener:self];

swift

BIMManager.sharedInstance().removeMsgListener(listener: self)
BIMManager.sharedInstance().removeConversationListener(listener: self)
BIMManager.sharedInstance().removeDiscussionListener(listener: self)
BIMManager.sharedInstance().removeSDKListener(listener: self)

8. 常见问题（FAQ）

JWT 过期：重新从业务后台获取 JWT 并重新登录
网络断开：SDK 会按配置自动重连
Pod 集成失败：检查 CocoaPods 版本和私有源配置
架构/打包失败：确认 xcframework 包含目标架构（如 arm64）

9. 错误处理

各模块的失败回调都会返回业务错误码和描述。音视频错误码及处理建议见音视频接入总览，其他模块请参考对应 API 文档。

10. 版本说明

当前示例以 BIMSdk 1.0.7 公共接口为准。升级 SDK 后请同时更新 Core 和可选音视频模块，避免二进制版本不一致。

BIMSdk iOS 接入文档 ​

1. 接入前置与环境要求 ​

1.1 软硬件要求 ​

1.2 账号与权限 ​

2. 集成方式 ​

2.1 CocoaPods（推荐） ​

2.2 xcframework（手动集成） ​

3. 快速开始（5 分钟跑通） ​

3.1 初始化 ​

3.2 登录 ​

3.3 获取会话列表 ​

3.4 进入会话并发送消息 ​

4. 鉴权与登录说明 ​

4.1 JWT 获取与登录 ​

4.2 登录状态与多端登录 ​

4.3 退出登录 ​

5. 消息与会话 ​

5.1 消息类型与限制 ​

5.2 拉取历史消息 ​

5.3 发送图片/文件/语音/视频 ​

5.4 会话设置 ​

5.5 自定义消息 ​

5.6 APNS 推送 ​

6. 好友与群组（简版） ​

6.1 好友申请 ​

6.2 创建群组 ​

7. 回调监听 ​

7.1 连接状态监听 ​

7.2 消息监听（BIMMsgListener） ​

7.3 会话监听（BIMConversationListener） ​

7.4 群组监听（BIMDiscussionListener） ​

7.5 页面销毁时移除监听（建议） ​

8. 常见问题（FAQ） ​

9. 错误处理 ​

10. 版本说明 ​

BIMSdk iOS 接入文档

1. 接入前置与环境要求

1.1 软硬件要求

1.2 账号与权限

2. 集成方式

2.1 CocoaPods（推荐）

2.2 xcframework（手动集成）

3. 快速开始（5 分钟跑通）

3.1 初始化

3.2 登录

3.3 获取会话列表

3.4 进入会话并发送消息

4. 鉴权与登录说明

4.1 JWT 获取与登录

4.2 登录状态与多端登录

4.3 退出登录

5. 消息与会话

5.1 消息类型与限制

5.2 拉取历史消息

5.3 发送图片/文件/语音/视频

5.4 会话设置

5.5 自定义消息

5.6 APNS 推送

6. 好友与群组（简版）

6.1 好友申请

6.2 创建群组

7. 回调监听

7.1 连接状态监听

7.2 消息监听（BIMMsgListener）

7.3 会话监听（BIMConversationListener）

7.4 群组监听（BIMDiscussionListener）

7.5 页面销毁时移除监听（建议）

8. 常见问题（FAQ）

9. 错误处理

10. 版本说明