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

# Android SDK 接入指南

**版本**：0.2.x（v0.4.0 将引入 UserSig 鉴权）· **最低 Android 版本**：API 24 (Android 7.0) · **语言**：Kotlin

> **注意**：v0.4.0 将是 Breaking 版本，`initialize()` 将保持不变，`ImSDK.login()` 将改为 UserSig 鉴权模式。

## 功能模块

| 模块 | Artifact | 功能 |
|------|----------|------|
| sdk-core | `com.xuqm:sdk-core` | 初始化、网络、鉴权（EncryptedSharedPreferences）|
| sdk-im | `com.xuqm:sdk-im` | 单聊、群聊、消息收发、会话、好友、群组 |
| sdk-push | `com.xuqm:sdk-push` | 自动检测厂商、设备 Token 注册 |
| sdk-update | `com.xuqm:sdk-update` | App 更新检查、RN 热更新 |

## 快速接入

### 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.2.0")
    implementation("com.xuqm:sdk-im:0.2.0")
    implementation("com.xuqm:sdk-push:0.2.0")    // 按需
    implementation("com.xuqm:sdk-update:0.2.0")  // 按需
}
```

### 2. 初始化

只需传入 `appKey`，服务器地址由 SDK 内置，**无需传 `serverUrl`**。

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

### 3. IM 登录与收消息

```kotlin
// 登录（协程 suspend 函数）
lifecycleScope.launch {
    ImSDK.login(userId = "user_001", nickname = "张三")
}

// 监听实时消息
ImSDK.addListener(object : ImEventListener {
    override fun onConnected() { /* WebSocket 已连接 */ }
    override fun onMessage(msg: ImMessage) { /* 单聊消息 */ }
    override fun onGroupMessage(msg: ImMessage) { /* 群聊消息 */ }
    override fun onDisconnected(reason: String?) { /* 断线处理 */ }
})
```

### 4. 发送消息

```kotlin
// 发送文本（通过 WebSocket 实时发送）
ImSDK.sendMessage(
    toId = "user_002",
    chatType = "SINGLE",
    msgType = "TEXT",
    content = """{"text":"Hello!"}""",
)
```

### 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.markRead(targetId)
```

### 6. 推送设备注册

```kotlin
// 登录后调用；SDK 自动检测手机厂商（华为/小米/OPPO/vivo/荣耀）
PushSDK.registerDevice(context, userId = "user_001")
```

### 7. 版本更新

```kotlin
// 检查 App 更新
val update = UpdateSDK.checkAppUpdate(context)
if (update?.needsUpdate == true) {
    UpdateSDK.downloadAndInstall(context, update.downloadUrl)
}
```

[→ 完整 API Reference](./api)