Client SDK 使用指南

本文说明一期 Client SDK 的核心使用方式：创建客户端、初始化、登录、监听事件、读取会话、发送消息、同步和释放资源。

一期平台：Web、Tauri、iOS、Flutter、Android。方法参数可在 API 浏览器 查询。

选择平台

接入顺序

createClient()
register listeners
init(config)
login(request)
open conversations
send messages
sync when needed
logout()
dispose()

初始化

最小配置只需要服务地址和租户：

await client.init({
  wsUrl: 'wss://im.example.com/ws',
  httpUrl: 'https://im.example.com',
  tenantId: 'default',
  resourceProfile: 'mobile',
})

登录

await client.login({
  userId: 'u_10001',
  token: coreToken,
})

token 由业务服务端签发或换取。token 过期后刷新并更新：

client.events.onUserTokenExpired(async () => {
  const nextToken = await refreshCoreToken()
  await client.updateAccessToken({ accessToken: nextToken })
})

监听事件

先订阅，再初始化和登录：

const messageSub = client.events.onMessageReceived((event) => {
  // event.message -> append to timeline
})

const connectSub = client.events.onConnectReady((event) => {
  // update connection state
})

页面销毁或切换账号时取消订阅：

messageSub.unsubscribe()
connectSub.unsubscribe()

会话与消息

读取会话：

const conversations = await client.conversations.listConversationsByQuery({
  limit: 30,
  includeArchived: false,
})

打开时间线：

const timeline = await client.conversations.openConversationTimeline({
  conversationId: 'c_10001',
  limit: 30,
})

构建并发送文本消息：

const message = await client.messageBuilder.buildText({
  conversationId: 'c_10001',
  text: 'hello',
})

await client.messages.sendMessage({ message })

同步与诊断

错误和清理

业务层至少处理：

退出：

messageSub.unsubscribe()
connectSub.unsubscribe()

await client.logout()
await client.dispose()

同一账号会话结束后不要继续复用旧 client 实例。