XuqmGroup-Web/docs-site/docs/android/index.md

# Android SDK 接入指南

**版本**：0.5.x（UserSig 鉴权 · 简化登录）· **最低 Android 版本**：API 24 (Android 7.0) · **语言**：Kotlin

## 功能模块

| 模块 | Artifact | 功能 |
|------|----------|------|
| sdk-core | `com.xuqm:sdk-core` | 初始化、网络、鉴权 |
| 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 函数）
// 只需要 userId + userSig，不需要 nickname / avatar / 过期字段
lifecycleScope.launch {
    XuqmSDK.login(
        userId = "user_001",
        userSig = "your_user_sig_jwt",   // 由业务服务端签发
    )
}

// 监听实时消息
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 在 `XuqmSDK.login()` 成功后会自动检测手机厂商、初始化对应 Push SDK、获取 Token 并上报到 Push 服务端。业务层**无需手动调用**任何 Push 注册 API。

如需主动控制，可调用：

```kotlin
// 检测当前设备厂商
val vendor = PushSDK.detectVendor()
// 返回：HUAWEI / XIAOMI / OPPO / VIVO / HONOR / FCM

// 开启或关闭推送接收
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. 多模块统一登录

无论集成了哪些模块（IM、Push、Update），**初始化和登录永远只做一次**：

```kotlin
// 初始化（Application.onCreate）
XuqmSDK.initialize(context, appKey = "your_app_key")

// 登录（业务登录成功后调用一次）
XuqmSDK.login(userId = "user_001", userSig = "jwt_token")
// ↓ 自动触发
//   · ImSDK.onSdkLogin    → 连接 WebSocket
//   · PushSDK.onSdkLogin  → 注册厂商 Token 并上报
//   · UpdateSDK.onSdkLogin → 无需额外操作（检查时自动携带凭证）

// 登出（业务退出时调用一次）
XuqmSDK.logout()
// ↓ 自动触发所有模块清理
```

> **注意**：`userSig` 由业务服务端签发，SDK 侧不做续签。若需更新登录态，请直接重新登录；如需撤销权限，可在租户平台重置 `appSecret` 或拉黑账号。

### 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)