IMSDK 接入指南
使用 BeeWorks IMSDK 为 Web、Android、iOS 与 HarmonyOS 应用接入即时通讯能力。本指南覆盖从创建应用、签发 JWT 到发送第一条消息的完整流程。
开始之前
请准备可用的 App ID、服务端地址，以及能够安全签发 JWT 的业务服务端。App 密钥只应保存在服务端，切勿写入客户端代码。
创建应用并准备凭据
在管理后台创建一个 IMSDK 应用，记录 App ID、服务地址，以及应用密钥中的 AccessKey 和 AccessSecret。客户端使用 App ID 标识应用，业务服务端使用应用密钥签发用户登录令牌。
建议为开发、测试和生产环境分别创建应用，避免测试数据与生产会话混用。
| 配置项 | 使用位置 | 说明 |
|---|---|---|
| App ID | 客户端 | 标识当前 IMSDK 应用 |
| Base URL | 客户端 | REST 与资源服务地址 |
| IM Endpoint | 客户端 | 长连接服务地址 |
| AccessKey | 业务服务端 | 应用密钥标识，写入 JWT Header 的 kid |
| AccessSecret | 业务服务端 | 使用 HS256 签名 JWT 的密钥，不得下发到客户端 |
安装并初始化 SDK
选择目标平台并安装对应依赖。下面以 Browser JS SDK 为例：
bash
npm install @beeworks/imsdk在应用启动阶段创建客户端，并配置应用信息与连接地址：
ts
import { IMClient } from '@beeworks/imsdk'
const client = IMClient.init({
appId: 'YOUR_APP_ID',
baseUrl: 'https://api.example.com',
endpoint: 'im.example.com:8029'
})移动端应用应在应用生命周期入口完成初始化，并确保同一进程只初始化一次。
签发用户 JWT
JWT 必须由业务服务端签发。客户端先向自己的业务服务端请求登录令牌，再把令牌交给 IMSDK 完成认证。
签发时，将应用密钥中的 AccessKey 写入 Header 的 kid，使用同一应用密钥中的 AccessSecret 进行 HS256 签名，并将接入方系统的用户 ID 写入 Payload 的 sub。
完整字段说明及可运行的 Java 示例见 JWT 令牌生成规范。
AccessSecret 属于高敏感凭据，仅保存在业务服务端。JWT 使用签名而非加密，Payload 可被解码读取，不应放入密码或密钥。
登录并建立连接
获取 JWT 后调用登录接口。SDK 会完成鉴权、用户数据加载、长连接建立与心跳维护。
ts
const { token } = await fetch('/api/im/token').then(res => res.json())
await client.login({
userId: 'user_10001',
token
})
client.on('connectionChanged', status => {
console.log('IM connection:', status)
})登录成功后即可安全调用会话、消息、好友和群组能力。网络切换时 SDK 会自动尝试恢复连接。
创建会话并发送消息
获取或创建会话，然后构造文本消息并发送。发送结果会通过 Promise 与事件监听器同步到界面。
ts
const conversation = await client.conversations.createDirect({
targetUserId: 'user_10002'
})
const message = await conversation.sendText({
text: 'Hello from BeeWorks IMSDK'
})
console.log('message sent:', message.id)监听新消息事件，为当前会话更新消息列表，并为其他会话累计未读数：
ts
client.on('messageReceived', message => {
messageStore.append(message.conversationId, message)
unreadStore.refresh(message.conversationId)
})验证接入结果
完成以下检查，确认基础链路已经跑通：
- 两个测试用户都能正常登录，连接状态为
connected。 - 用户 A 能创建与用户 B 的会话并发送文本消息。
- 用户 B 能实时收到消息，重启应用后仍能拉取历史记录。
- 断网再恢复后 SDK 能自动重连，消息状态能够正确更新。
接入完成后，可继续配置图片与文件消息、群聊、好友关系、离线推送和消息回执等能力。
接入客户端SDKs
- 按平台查看 Browser JS SDK、Android SDK、iOS SDK 或 HarmonyOS SDK 的详细说明。
- 在 代码示例 中查看完整场景和推荐实现。
- 进入 API 参考查阅用户、会话、消息、群组与事件接口。