BIMSdk Android 接入文档

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

适用范围：BIMSdk Android（Kotlin / Java），本文档为统一接入版，后续会拆分为业务模块文档。

1. 接入前置与环境要求

1.1 软硬件要求

• Android 最低版本：API 24 (Android 7.0)+
• 编译工具：Android Studio Hedgehog (2023.1.1) 及以上
• Gradle 版本：8.0+
• Kotlin / Java：均支持（推荐 Kotlin）

1.2 账号与权限

• 需要从 BIM 平台申请 AppId 与 BaseURL
• JWT 需由接入方后台与 BIM 后台交互获取（参考 4.1）

---

2. 集成方式

2.1 Gradle 集成（推荐）

在项目根目录的 build.gradle 或 settings.gradle 中配置 Maven 仓库：

repositories {
     maven {
            url = uri("https://packages.aliyun.com/maven/repository/2125526-release-qv8CDO/")

            credentials {
                username = "6100de6ecd146a5e9c6d9402"
                password = "ZdZYab-]7Aqo"
            }
        }
}

在模块的 build.gradle 中添加依赖：

dependencies {
    implementation 'com.beeworks.im:chat:1.1.0'
}

2.2 离线 AAR 集成

• 将 bimsdk-release.aar 放入模块的 libs 目录。
• 确保 build.gradle 包含：

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
}

---

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

目标：完成 初始化 → 登录 → 拉取会话 → 发送消息。

3.1 初始化

建议在 Application.onCreate 中调用：

// Kotlin
val config = BimImConfig.Builder()
    .setBaseUrl("https://example.com") // 替换为实际 BaseURL
    .setImEndpoint("example.com:8029") // 替换为实际 IMEndPoint
    .build()

BimImManager.getInstance().init(this, "yourAppId", config)
BimImManager.getInstance().addSdkListener(sdkListener)

// Java
BimImConfig config = new BimImConfig.Builder()
    .setBaseUrl("https://example.com")
    .setImEndpoint("example.com:8029")
    .build();

BimImManager.getInstance().init(context, "yourAppId", config);

3.2 登录

// Kotlin
val userId = "user01"
val jwt = "<server-issued-jwt>"

BimImManager.getInstance().baseCoreService.login(userId, jwt, object : BimResultCallback<Unit> {
    override fun onSuccess(data: Unit) {
        // 登录成功
    }
    override fun onError(code: Int, msg: String) {
        // 登录失败
    }
})

3.3 获取会话列表

// Kotlin
BimImManager.getInstance().conversationService.fetchConversationList(object : BimResultCallback<List<BimConversation>> {
    override fun onSuccess(list: List<BimConversation>) {
        // 更新 UI 列表
    }
    override fun onError(code: Int, msg: String) {}
})

3.4 进入会话并发送消息

// Kotlin
val conversation: BimConversation = ... // 来自列表点击
val textMsg = BimImManager.getInstance().chatService.createTextMessage("hello", false, null)

BimImManager.getInstance().sendMessage(textMsg, conversation, object : BimSendCallback {
    override fun onProgress(progress: Double) {
        // 进度更新
    }
    override fun onSuccess(message: BimMessage) {
        // 发送成功
    }
    override fun onError(code: Int, msg: String) {
        // 发送失败
    }
})

---

4. 鉴权与登录说明

4.1 JWT 获取与登录

• JWT 由接入方后台获取并下发给客户端。
• 客户端调用 login 接口后，SDK 会自动管理心跳与长连接。

4.2 登录状态与多端登录

• 登录状态：BimLoginStatus (IDLE, LOGGING, LOGGED_IN, KICKED_OFFLINE)。
• 多端策略：请补充（默认同端互踢）。

4.3 退出登录

BimImManager.getInstance().baseCoreService.logout(object : BimResultCallback<Unit> {
    override fun onSuccess(data: Unit) { /* 登出成功 */ }
    override fun onError(code: Int, msg: String) {}
})

---

5. 消息与会话

5.1 消息类型与限制

• 支持：文本 / 图片 / 文件 / 语音 / 视频。
• 媒体限制：文件消息上限为 100MB。

5.2 拉取历史消息

// lastMsg: 分页游标，首次拉取传 null
BimImManager.getInstance().chatService.getMessages(conversation, lastMsg, 50, object : BimResultCallback<List<BimMessage>> {
    override fun onSuccess(list: List<BimMessage>) {
        // 渲染消息历史
    }
    override fun onError(code: Int, msg: String) {}
})

5.3 会话设置（如置顶、免打扰）

val setting = BimConversationSetting().apply {
    isPinned = true
}
BimImManager.getInstance().conversationService.updateConversationSetting(conversation, setting, object : BimResultCallback<Unit> {
    override fun onSuccess(data: Unit) {}
    override fun onError(code: Int, msg: String) {}
})

---

6. 好友与群组（简版）

6.1 好友申请

BimImManager.getInstance().friendService.applyFriend(userId, "你好，我是XXX", object : BimResultCallback<Unit> {
    override fun onSuccess(data: Unit) {}
    override fun onError(code: Int, msg: String) {}
})

6.2 创建群组/讨论组

BimImManager.getInstance().discussionService.createDiscussion(
    name = "项目讨论组",
    avatar = "",
    members = listOf("user01", "user02"),
    callback = object : BimResultCallback<BimDiscussion> {
        override fun onSuccess(data: BimDiscussion) {}
        override fun onError(code: Int, msg: String) {}
    }
)

---

7. 回调监听

7.1 SDK 状态与事件

实现 BimSdkListener 接口：

• onConnecting(): 正在连接。
• onConnected(): 连接成功。
• onConnectFailed(code, msg): 连接失败。
• onKickedOffline(): 被踢下线（多端登录冲突）。
• onNewMessage(message): 收到新消息。

---

8. 常见问题（FAQ）

• Q: 收到消息没通知？
  • A: 检查是否调用了 addSdkListener，且在会话列表或聊天页正确过滤了 ID。
• Q: 图片/视频发送失败？
  • A: 确保已获得运行时权限 READ_EXTERNAL_STORAGE。
• Q: 混淆配置？
  • A: 请在 proguard-rules.pro 中添加： -keep class com.bim.sdk.** { *; }

---

9. 错误码对照表

code	含义	处理建议
1001	JWT 格式错误	检查后台生成的 JWT 是否包含正确 Claim
1002	网络超时	检查 imEndpoint 是否能 Ping 通
2001	文件过大	压缩图片或确认文件小于 100MB

---