XuqmGroup 7b7989525f feat(sdk): 更新 SDK 设计文档和 API 重构

- 添加 expiresAt 和 refreshUserSig 参数支持自动续签
- 修改 PushSDK 初始化方式，自动完成设备注册和厂商初始化
- 调整过期续签策略，从提前 15 分钟改为提前 5 分钟触发
- 重构 RN SDK 文档结构，简化安装和使用方式
- 更新统一登录流程，支持 profile 信息传递
- 添加 IM 数据库自动隔离功能
- 修复 Android 群消息聚合问题
- 补充自动化测试验证和错误处理机制

2026-05-01 21:27:39 +08:00

5.9 KiB

原始文件 Blame 文件历史

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. 添加依赖

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        maven("https://nexus.xuqinmin.com/repository/android/")
        google(); mavenCentral()
    }
}

// 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。

// Application.onCreate()
XuqmSDK.initialize(
    context = this,
    appKey = "your_app_key",         // 在租户平台创建应用后获得
    logLevel = LogLevel.WARN,        // 可选，DEBUG 开启详细日志
)

3. IM 登录与收消息（UserSig 模式）

// 登录（协程 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. 发送消息

// 发送文本
ImSDK.sendTextMessage(
    toId = "user_002",
    chatType = "SINGLE",
    content = "Hello!",
)

// 发送图片（需先调用 FileSDK 上传）
ImSDK.sendImageMessage(
    toId = "user_002",
    chatType = "SINGLE",
    file = uploadResult,
    width = 800,
    height = 600,
)

5. 群组、好友、会话

// 群组
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 服务。业务层通常无需手动调用，但可根据需要主动控制：

// 手动检测当前设备厂商
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 和定时器。

// 设置续签监听器（建议在初始化后、登录前设置）
XuqmSDK.setUserSigRefreshListener {
    // 异步获取新 UserSig
    lifecycleScope.launch {
        val newUserSig = yourBackend.refreshUserSig("user_001")
        XuqmSDK.login(
            userId = "user_001",
            userSig = newUserSig,
            userSigExpiresAt = newExpiryTimeMs,
        )
    }
}

注意：userSigExpiresAt 为 Unix 时间戳（毫秒）。若登录时不传该值，则不会启动续签定时器。

8. 版本更新

// 检查 App 更新
val update = UpdateSDK.checkAppUpdate(context)
if (update?.needsUpdate == true) {
    UpdateSDK.downloadAndInstall(context, update.downloadUrl) { progress ->
        // 更新下载进度 0-100
    }
}

9. 连接状态监听

// 通过 StateFlow 监听 IM 连接状态
lifecycleScope.launch {
    ImSDK.connectionState.collect { state ->
        when (state) {
            is ImConnectionState.Connected -> { /* 已连接 */ }
            is ImConnectionState.Connecting -> { /* 连接中 */ }
            is ImConnectionState.Disconnected -> { /* 已断开：state.reason */ }
        }
    }
}

→ 完整 API Reference

5.9 KiB 原始文件 Blame 文件历史 Unescape Escape