7b7989525f
- 添加 expiresAt 和 refreshUserSig 参数支持自动续签 - 修改 PushSDK 初始化方式，自动完成设备注册和厂商初始化 - 调整过期续签策略，从提前 15 分钟改为提前 5 分钟触发 - 重构 RN SDK 文档结构，简化安装和使用方式 - 更新统一登录流程，支持 profile 信息传递 - 添加 IM 数据库自动隔离功能 - 修复 Android 群消息聚合问题 - 补充自动化测试验证和错误处理机制
199 行
5.9 KiB
Markdown
199 行
5.9 KiB
Markdown
# Android SDK 接入指南
|
||
|
||
**版本**：0.4.x（UserSig 鉴权）· **最低 Android 版本**：API 24 (Android 7.0) · **语言**：Kotlin
|
||
|
||
## 功能模块
|
||
|
||
| 模块 | Artifact | 功能 |
|
||
|------|----------|------|
|
||
| sdk-core | `com.xuqm:sdk-core` | 初始化、网络、鉴权、UserSig 续签 |
|
||
| sdk-im | `com.xuqm:sdk-im` | 单聊、群聊、消息收发、会话、好友、群组 |
|
||
| sdk-push | `com.xuqm:sdk-push` | 自动检测厂商、设备 Token 注册（华为/小米/OPPO/vivo/荣耀/FCM） |
|
||
| sdk-update | `com.xuqm:sdk-update` | App 更新检查、下载安装 |
|
||
|
||
## 快速接入
|
||
|
||
### 1. 添加依赖
|
||
|
||
```kotlin
|
||
// settings.gradle.kts
|
||
dependencyResolutionManagement {
|
||
repositories {
|
||
maven("https://nexus.xuqinmin.com/repository/android/")
|
||
google(); mavenCentral()
|
||
}
|
||
}
|
||
```
|
||
|
||
```kotlin
|
||
// app/build.gradle.kts
|
||
dependencies {
|
||
implementation("com.xuqm:sdk-core:0.4.0")
|
||
implementation("com.xuqm:sdk-im:0.4.0")
|
||
implementation("com.xuqm:sdk-push:0.4.0") // 按需
|
||
implementation("com.xuqm:sdk-update:0.4.0") // 按需
|
||
}
|
||
```
|
||
|
||
### 2. 初始化
|
||
|
||
只需传入 `appKey`，服务器地址由 SDK 内置，**无需传 `serverUrl`**。
|
||
|
||
```kotlin
|
||
// Application.onCreate()
|
||
XuqmSDK.initialize(
|
||
context = this,
|
||
appKey = "your_app_key", // 在租户平台创建应用后获得
|
||
logLevel = LogLevel.WARN, // 可选，DEBUG 开启详细日志
|
||
)
|
||
```
|
||
|
||
### 3. IM 登录与收消息（UserSig 模式）
|
||
|
||
```kotlin
|
||
// 登录（协程 suspend 函数）
|
||
lifecycleScope.launch {
|
||
XuqmSDK.login(
|
||
userId = "user_001",
|
||
userSig = "your_user_sig_jwt", // 由业务服务端签发
|
||
nickname = "张三",
|
||
avatar = "https://...",
|
||
userSigExpiresAt = 1893456000000L, // UserSig 过期时间戳（毫秒），可选
|
||
)
|
||
}
|
||
|
||
// 监听实时消息
|
||
ImSDK.addListener(object : ImEventListener {
|
||
override fun onConnected() { /* WebSocket 已连接 */ }
|
||
override fun onMessage(msg: ImMessage) { /* 单聊消息 */ }
|
||
override fun onGroupMessage(msg: ImMessage) { /* 群聊消息 */ }
|
||
override fun onRead(msg: ImMessage) { /* 对方已读回执 */ }
|
||
override fun onRevoke(msg: ImMessage) { /* 消息被撤回 */ }
|
||
override fun onDisconnected(reason: String?) { /* 断线处理 */ }
|
||
override fun onError(error: String) { /* 错误回调 */ }
|
||
})
|
||
```
|
||
|
||
### 4. 发送消息
|
||
|
||
```kotlin
|
||
// 发送文本
|
||
ImSDK.sendTextMessage(
|
||
toId = "user_002",
|
||
chatType = "SINGLE",
|
||
content = "Hello!",
|
||
)
|
||
|
||
// 发送图片（需先调用 FileSDK 上传）
|
||
ImSDK.sendImageMessage(
|
||
toId = "user_002",
|
||
chatType = "SINGLE",
|
||
file = uploadResult,
|
||
width = 800,
|
||
height = 600,
|
||
)
|
||
```
|
||
|
||
### 5. 群组、好友、会话
|
||
|
||
```kotlin
|
||
// 群组
|
||
val groups = ImSDK.listGroups()
|
||
val group = ImSDK.createGroup("项目讨论", listOf("user_002", "user_003"))
|
||
ImSDK.addGroupMember(groupId, "user_004")
|
||
ImSDK.leaveGroup(groupId)
|
||
|
||
// 好友
|
||
val friends = ImSDK.listFriends()
|
||
ImSDK.addFriend("user_002")
|
||
|
||
// 会话
|
||
val conversations = ImSDK.listConversations()
|
||
ImSDK.setConversationPinned(targetId, "SINGLE", true)
|
||
ImSDK.setConversationMuted(targetId, "SINGLE", true)
|
||
ImSDK.markRead(targetId, "SINGLE")
|
||
ImSDK.setDraft(targetId, "SINGLE", "草稿内容")
|
||
ImSDK.deleteConversation(targetId, "SINGLE")
|
||
```
|
||
|
||
### 6. Push 多厂商接入
|
||
|
||
SDK 在登录后会自动检测手机厂商并初始化对应 Push 服务。业务层通常无需手动调用，但可根据需要主动控制：
|
||
|
||
```kotlin
|
||
// 手动检测当前设备厂商
|
||
val vendor = PushSDK.detectVendor()
|
||
// 返回：HUAWEI / XIAOMI / OPPO / VIVO / HONOR / FCM
|
||
|
||
// 手动初始化各厂商 Push SDK（通常由 onSdkLogin 自动调用）
|
||
PushSDK.initializeVendors(context)
|
||
|
||
// 手动绑定/解绑 IM 用户与 Push Token
|
||
PushSDK.bindImUser(context, userId = "user_001")
|
||
PushSDK.unbindImUser(userId = "user_001")
|
||
|
||
// 开启或关闭推送接收
|
||
PushSDK.setReceivePush(context, enabled = false)
|
||
```
|
||
|
||
**各厂商接入注意事项**：
|
||
|
||
| 厂商 | 需额外依赖 | 说明 |
|
||
|------|-----------|------|
|
||
| 华为 | `com.huawei.hms:push` | 需在华为开发者平台配置 AppID |
|
||
| 小米 | `com.xiaomi.mipush:mipush-sdk` | 需在小米开放平台申请 AppID/AppKey |
|
||
| OPPO | `com.heytap.mcssdk:mcssdk` | 需在 OPPO 开放平台申请 |
|
||
| vivo | `com.vivo.push:vivopush` | 需在 vivo 开放平台申请 |
|
||
| 荣耀 | `com.hihonor.mcs:mcs-push` | 需在荣耀开发者服务平台配置 |
|
||
| FCM | `com.google.firebase:firebase-messaging` | 模拟器无 Google Play 服务时会 fallback |
|
||
|
||
### 7. UserSig 续签
|
||
|
||
在 `UserSig` 即将过期（默认提前 5 分钟）时，SDK 会触发续签回调。业务层应在回调中向自己的服务端申请新的 UserSig，然后重新调用 `XuqmSDK.login()` 刷新 Token 和定时器。
|
||
|
||
```kotlin
|
||
// 设置续签监听器（建议在初始化后、登录前设置）
|
||
XuqmSDK.setUserSigRefreshListener {
|
||
// 异步获取新 UserSig
|
||
lifecycleScope.launch {
|
||
val newUserSig = yourBackend.refreshUserSig("user_001")
|
||
XuqmSDK.login(
|
||
userId = "user_001",
|
||
userSig = newUserSig,
|
||
userSigExpiresAt = newExpiryTimeMs,
|
||
)
|
||
}
|
||
}
|
||
```
|
||
|
||
> **注意**：`userSigExpiresAt` 为 Unix 时间戳（毫秒）。若登录时不传该值，则不会启动续签定时器。
|
||
|
||
### 8. 版本更新
|
||
|
||
```kotlin
|
||
// 检查 App 更新
|
||
val update = UpdateSDK.checkAppUpdate(context)
|
||
if (update?.needsUpdate == true) {
|
||
UpdateSDK.downloadAndInstall(context, update.downloadUrl) { progress ->
|
||
// 更新下载进度 0-100
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9. 连接状态监听
|
||
|
||
```kotlin
|
||
// 通过 StateFlow 监听 IM 连接状态
|
||
lifecycleScope.launch {
|
||
ImSDK.connectionState.collect { state ->
|
||
when (state) {
|
||
is ImConnectionState.Connected -> { /* 已连接 */ }
|
||
is ImConnectionState.Connecting -> { /* 连接中 */ }
|
||
is ImConnectionState.Disconnected -> { /* 已断开：state.reason */ }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
[→ 完整 API Reference](./api)
|
