Android Kotlin 兼容接入

Android 新项目默认阅读 Java/XML 接入。如果现有工程已经统一使用 Kotlin 协程，可以按本页调用同一套 SDK。

1. 安装

dependencies {
    implementation("com.xihansoftware.xhim:xhim-sdk:0.1.0-dev.10")
}

仓库地址和凭据由 XHIM 交付人员提供，不要写入源码仓库。

2. 连接账号

开发环境：

val client = XHIMClient.connect(
    context = applicationContext,
    server = "https://im.example.com",
    userId = currentUser.id,
)

生产环境由业务后台提供短期凭证：

val client = XHIMClient.connect(
    context = applicationContext,
    server = "https://im.example.com",
    userId = currentUser.id,
    appId = "your-app-id",
    authentication = XHIMAuthentication.Business {
        accountApi.fetchXHIMAccessToken()
    },
)

Client 应由账号级 Service 或 ViewModel 持有，不要在 Fragment 每次创建视图时重复连接。

3. 监听事件

val eventJob = lifecycleScope.launch {
    client.events.collect { event ->
        when (event) {
            is XHIMEvent.ConversationChanged -> reloadConversations()
            is XHIMEvent.MessageUpserted -> reloadMessages(event.change.conversationId)
            else -> Unit
        }
    }
}

页面销毁时取消 eventJob；账号 Client 可以继续由上层持有。

4. 发送第一条消息

val conversation = client.directConversation("bob")
val receipt = client.sendText(
    conversationId = conversation.conversationId,
    text = "你好，XHIM",
)

使用第二个账号确认接收、已读和断网恢复，再继续开发图片、群组和自定义消息。

5. 退出和换号

eventJob.cancel()
client.logout()
client.shutdown()

换号时创建新账号对应的 Client，不复用旧账号对象或本地数据目录。

6. 常用方法

任务	方法
创建或获取单聊	directConversation(peerUserId)
发送文字	sendText(...)
查询会话	conversations(...)
查询消息	messages(...) / getMessageHistory(...)
查询好友	friendships(...)
查询群组	groups(...) / groupMembers(...)
更新凭证	updateCredential(accessToken)
网络恢复	notifyNetworkAvailable()

完整参数、返回值和错误说明见 SDK API Reference。

7. 常见问题

• 协程取消后页面仍刷新：检查是否在其他作用域重复收集 client.events；
• 连接被拒绝：确认 Server URL、App ID、User ID 和短期凭证属于同一环境；
• 能发送但列表不更新：收到事件后重新查询当前会话或消息；
• Java 项目如何接入：直接使用 Android Java/XML 接入，不要调用带 Continuation 的 Kotlin 字节码方法。