Android IMLib 快速开始

本页用 5 个步骤完成 Android 端 IMLib 接入：控制台取 AppKey / Token、导入 SDK、初始化、建立连接、收发消息与会话。示例方法名与参数来自冻结的 sdk-bindings.json。

  1. 控制台获取 AppKey 与 Token

    在控制台创建应用并获取 AppKey；用户 Token 由业务服务先注册用户（user.register）、再调用 user.token.issue 签发后下发到客户端（两步都需要服务端签名）。

    客户端只持有 Token，不得内置 AppSecret；Token 泄露时可调用服务端接口吊销。

  2. 导入 SDK

    按「导入 SDK」安装依赖；Maven 坐标 io.nipaas:imlib / io.nipaas:imkit 对应源码模块 sdk/android/imlib、sdk/android/imkit；仓库内联调可用 include(":imlib") 源码集成。

  3. 初始化客户端

    使用 AppKey（与服务端地址）初始化；初始化幂等：同 appkey 重复调用返回同一实例，不建立连接。

  4. 建立连接并订阅事件

    使用 Token 调用 connect，成功后触发 CONNECTED；离线消息在 hello 后自动补发。

  5. 收发消息与会话

    注册对端用户后发送第一条文本消息、监听 MESSAGES 事件并拉取会话列表。

1. 控制台获取 AppKey 与 Token​

凭据获取方式使用位置
AppKey控制台 → 应用 → 基本信息初始化客户端（options.appkey）
用户 Token业务服务注册用户（user.register）后调用 user.token.issue 签发（需签名）connect(token)
AppSecret控制台 → 应用 → 密钥（仅服务端保存）服务端签发 Token / 调用 Open API
禁止硬编码

AppSecret 只能保存在业务服务端；客户端产物中不得出现 AppSecret。示例中的 TOKEN 表示服务端签发的用户 Token。

本地服务端地址

本页及后续示例统一使用 https://im.example.com（服务端缺省端口）。

示例使用占位地址 https://im.example.com；本地联调请替换为你实际启动的服务端地址与端口（客户端与服务端必须指向同一地址）。

2. 导入 SDK​

Gradle（Kotlin DSL）
// app/build.gradle.kts
dependencies {
    implementation("io.nipaas:imlib:1.0.0")   // IMLib：无 UI 通信库
    implementation("io.nipaas:imkit:1.0.0")   // 可选：IMKit UI 组件
}

环境要求​

项要求说明
JDK17+Gradle 8.11.1 兼容 JDK 17/21；JAVA_HOME 指向 JDK
Android SDKcompileSdk 35 / build-tools 35.0.0设置 ANDROID_HOME；minSdk 24
Kotlin / AGPKotlin 2.0.21 / AGP 8.7.3随仓库 sdk/android 提供
设备/模拟器Android 7.0（API 24）及以上需要 INTERNET、ACCESS_NETWORK_STATE 权限
推送（可选）Android 13+ 需 POST_NOTIFICATIONS 运行时授权仅离线推送场景需要

3. 初始化​

Kotlin
val client = IMClient.init(
    context = applicationContext,
    options = IMClientOptions(appkey = "YOUR_APP_KEY", serverUrl = "https://im.example.com"),
)

4. 建立连接​

Kotlin
client.addEventListener(IMClientEvent.CONNECTED) { /* 已连接，离线消息补发完成 */ }
client.connect(TOKEN, object : ConnectCallback {
    override fun onSuccess(userId: String) { /* 建连成功 */ }
    override fun onError(error: IMError) { /* 1002 Token 无效 / 3002 超时 */ }
})

5. 收发消息与会话​

收发验证需要两个已注册用户：先注册对端（例如 user2）并签发它的 Token，再用对端账号建连接收。示例中的 user2 是“已存在的另一个用户”，不是任意字符串。

Kotlin
client.addEventListener(IMClientEvent.MESSAGES) { payload ->
    // payload 为 {messages: Message[]}；按会话聚合、更新未读数
}
client.sendTextMessage(
    conversationType = ConversationType.PRIVATE,
    targetId = "user2",
    text = "你好，NI PaaS",
    callback = object : SendMessageCallback {
        override fun onSuccess(message: Message) { /* 发送成功 */ }
        override fun onError(error: IMError) { /* 处理 error.code */ }
    },
)
client.getConversationList(object : ResultCallback<List<Conversation>> {
    override fun onSuccess(result: List<Conversation>) { /* 渲染会话列表 */ }
    override fun onError(error: IMError) { /* ... */ }
})
发送给未注册用户会断开连接

单聊发送给不存在的用户时，服务端返回 1004（用户不存在），当前连接可能因此被断开，随后发送调用返回 3001（连接已中断）。

这不是网络故障：注册对端用户（user.register）并重连后即可正常发送。排查时先确认两个 userId 都已注册且属于同一个 appkey。

响应不是 JSON / 404？

如果脚本报 Unexpected token '<' 或看到 HTML，通常是服务端地址或端口不对（示例使用占位地址；本地联调要替换为实际端口）。

先用浏览器或 curl 访问服务端根路径确认可达，再检查 serverUrl 是否与启动参数一致。

双端验证：两个进程 / 两个浏览器 profile

同一进程内对同一个 appkey 初始化只会得到一个客户端实例（初始化幂等）：把两个账号塞进同一个实例会互相覆盖登录态，典型报错是 “cannot send to self”。

实测：同一进程内建两个客户端实例（不同 appkey 或先 destroy 再 create）可以互发；同 origin 的两个浏览器标签共享 deviceId，第二个客户端可能收不到投递。

因此本机验证“收发”请开两个进程，或开两个浏览器 profile（各自独立 localStorage/deviceId），每个进程/Profile 只登录一个用户。

下一步​