XuqmGroup-AndroidSDK/README.md

XuqmGroup Android SDK 文档

Kotlin 2.3.10 · AGP 9.1.0 · minSdk 24 · compileSdk 36

模块结构

XuqmGroup-AndroidSDK/
├── sdk-core/        # 核心：初始化、HTTP、Token 存储
├── sdk-im/          # IM：WebSocket 实时通信
├── sdk-push/        # 推送：设备 Token 注册
├── sdk-update/      # 版本管理：检查更新、下载安装、RN 热更新
└── sample-app/      # 示例 App（Jetpack Compose）

集成

Gradle（Maven 私有仓库）

在项目根 settings.gradle.kts 添加仓库：

dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://nexus.xuqinmin.com/repository/android-hosted/")
            credentials {
                username = providers.gradleProperty("NEXUS_USER").orNull ?: ""
                password = providers.gradleProperty("NEXUS_PASSWORD").orNull ?: ""
            }
        }
    }
}

在 gradle.properties 或环境变量中配置：

NEXUS_USER=your_username
NEXUS_PASSWORD=your_password

引入依赖：

dependencies {
    implementation("com.xuqm:sdk-core:0.1.0")
    implementation("com.xuqm:sdk-im:0.1.0")       // 可选
    implementation("com.xuqm:sdk-push:0.1.0")     // 可选
    implementation("com.xuqm:sdk-update:0.1.0")   // 可选
}

快速开始

1. 初始化（Application.onCreate）

XuqmSDK.init(
    context = this,
    appKey = "ak_your_app_key",
    appSecret = "as_your_app_secret",
    apiBaseUrl = "https://api.xuqm.com",
    imBaseUrl = "wss://im.xuqm.com",
    debug = BuildConfig.DEBUG
)

2. 用户登录后设置 Token

// 调用你的业务登录接口获得 token 后
XuqmSDK.tokenStore.save(token)

---

sdk-core

SDKConfig

参数	类型	说明
appKey	String	应用 Key（租户平台获取）
appSecret	String	应用 Secret
apiBaseUrl	String	后端 API 地址
imBaseUrl	String	IM WebSocket 地址（wss://）
debug	Boolean	开启日志

TokenStore

基于 DataStore<Preferences> 持久化存储。

// 存储
XuqmSDK.tokenStore.save("eyJ...")

// 读取（协程）
val token = XuqmSDK.tokenStore.get()

// 清除（登出）
XuqmSDK.tokenStore.clear()

ApiClient

基于 OkHttp 5 + Retrofit 3，自动附加 Bearer Token，统一解析 ApiResponse<T>。

// 通过 RetrofitFactory 获取接口实例
val service = RetrofitFactory.create(MyApiService::class.java)

---

sdk-im

ImClient

val imClient = ImClient()

// 注册事件监听
imClient.listener = object : ImEventListener {
    override fun onConnected() { /* WebSocket 连接成功 */ }
    override fun onDisconnected(code: Int, reason: String) { /* 断开 */ }
    override fun onMessage(msg: ImMessage) { /* 收到新消息 */ }
    override fun onRevoke(msgId: String, operatorId: String) { /* 消息被撤回 */ }
    override fun onError(t: Throwable) { /* 连接错误 */ }
}

// 连接
imClient.connect()

// 发送消息
imClient.send(SendMessageParams(
    toId = "user_002",
    chatType = ChatType.SINGLE,
    msgType = MsgType.TEXT,
    content = "Hello!"
))

// 撤回消息
imClient.revoke(msgId = "uuid")

// 断开连接（Activity/Fragment 销毁时调用）
imClient.disconnect()

消息类型（MsgType）

TEXT / IMAGE / VIDEO / AUDIO / FILE / CUSTOM / LOCATION / NOTIFY / RICH_TEXT / CALL_AUDIO / CALL_VIDEO / FORWARD

ImMessage 结构

data class ImMessage(
    val id: String,
    val fromId: String,
    val toId: String,
    val chatType: ChatType,     // SINGLE / GROUP
    val msgType: MsgType,
    val content: String,
    val extra: String?,
    val revoked: Boolean,
    val createdAt: String
)

自动重连

断线后指数退避重连，初始间隔 3 秒，最大间隔 30 秒。调用 disconnect() 后停止重连。

---

sdk-push

注册推送 Token

在获取到厂商推送 token 后调用：

PushSDK.registerToken(
    appId = "ak_xxx",
    userId = "user_001",
    vendor = Vendor.HUAWEI,  // HUAWEI / XIAOMI / OPPO / VIVO / HONOR / APNS
    token = "device_push_token"
)

与 IM 联动

当 IM 和推送服务均已开启时，IM 服务在目标用户离线时会自动调用推送服务发送离线推送通知。
业务方只需分别注册推送 Token 和 IM 登录，无需额外配置。

---

sdk-update

检查原生 App 更新

val result: UpdateResult = UpdateSDK.checkUpdate(
    appId = "ak_xxx",
    platform = Platform.ANDROID
)

if (result.needsUpdate) {
    // result.versionName, result.downloadUrl, result.forceUpdate
    UpdateSDK.downloadAndInstall(context, result.downloadUrl)
}

downloadAndInstall 会将 APK 下载到 getExternalFilesDir(null)，通过 FileProvider 触发系统安装。
AndroidManifest 中已配置 @xml/file_paths（external-files-path）。

检查 RN Bundle 更新

val rnResult = UpdateSDK.checkRnUpdate(
    appId = "ak_xxx",
    moduleId = "main",
    platform = "android",
    currentVersion = "1.0.0"
)

if (rnResult.needsUpdate) {
    val filePath = UpdateSDK.downloadBundle(context, rnResult.downloadUrl, "main.android.bundle")
    // 校验 MD5
    // 通知 RN 引擎加载新 bundle
}

---

发版

# 在 gradle.properties 中配置 NEXUS_USER / NEXUS_PASSWORD
./gradlew :sdk-core:publish
./gradlew :sdk-im:publish
./gradlew :sdk-push:publish
./gradlew :sdk-update:publish

发布至 https://nexus.xuqinmin.com/repository/android-hosted/，groupId com.xuqm，版本号在各模块 build.gradle.kts 中维护。