初始化 IM SDK 后，你需要调用 client.login 登录 SDK。登录成功后，SDK 会建立到消息服务的长连接，恢复本地缓存，按初始化配置同步会话列表、好友列表、群组和用户属性等数据。登录成功后，才能使用收发消息、会话管理、好友关系、群组管理等 IM 能力。

前提条件

开始前，请确保满足以下条件：

已完成 SDK 初始化，详见初始化文档。
登录、续期、退出登录及获取当前登录状态等能力通过 ChatClient 实例调用，无需额外注册 Manager。
已获取合法的用户 ID 和 Token。

用户注册

创建用户

即时通讯 IM 提供以下两种方式创建用户：

调用 RESTful API 注册用户账号，注册后保存到你的服务器或返给客户端。
在声网控制台open in new window按照如下步骤创建用户：

展开控制台左上角下拉框，选择需要开通即时通讯 IM 服务的项目。
点击左侧导航栏的全部产品。
在下拉列表中找到即时通讯 IM 并点击。
在即时通讯 IM 页面，进入运营管理标签页。
在用户页签下，点击创建IM用户。
在弹出的对话框中，配置用户相关参数，点击确定。

获取用户 token

创建用户后，在用户列表点击对应的用户的操作一栏中的更多，选择查看Token。

在弹出的对话框中，可以查看用户 Token，也可以点击重新生成，生成用户 token。

在生产环境中，为了安全考虑，你需要部署 App Server 生成 Token，详见 Token 鉴权文档。

userId 和 token 均为必填参数。
建议在调用 login 前注册连接事件监听，以便接收连接成功、连接断开以及 Token 生命周期相关事件。
若 SDK 已处于连接中或已连接状态，再次调用 login 会失败。
如需切换登录用户，请先调用 logout 登出当前用户，再使用新的用户 ID 和 Token 登录。

示例代码如下：

client.addEventHandler('login-listener', {
  onConnected: event => {
    console.log('登录并连接成功:', event);
  },
  onDisconnected: event => {
    console.log('连接断开:', event.reason, event.errorCode, event.errorMessage);
  },
  onTokenWillExpire: async () => {
    const newToken = await fetchNewTokenFromServer();
    await client.renewToken(newToken);
  },
  onTokenExpired: () => {
    console.log('Token 已过期，需要重新获取 Token 后登录');
  },
});

await client.login({
  userId: 'username',
  token: 'token',
});

提示

如果后续需要使用消息、会话、好友、群组等能力，请在初始化 SDK 时注册对应的 Manager。例如，使用消息和会话能力时需注册 ChatManager。

获取当前登录状态和信息

登录成功后，你可以调用以下方法获取当前连接状态、登录用户和设备资源标识。

方法	返回值	描述
`getConnectionState`	String	获取当前连接状态。取值包括 `disconnected`、`connecting`、`connected`、`reconnecting` 和 `reconnectFailed`。
`getCurrentUserId`	String \| null	获取当前登录用户 ID。未登录时返回 `null`。
`getClientResource`	String \| null	获取当前连接的设备资源标识。未连接或尚未完成登录握手时返回 `null`。
`getRestContext`	RestContext	获取当前登录会话的 REST 访问上下文，包括 REST 地址、App ID、用户 ID、Token 和设备资源标识。未登录或上下文不完整时会抛出错误。

const state = client.getConnectionState();
const userId = client.getCurrentUserId();
const clientResource = client.getClientResource();

console.log('连接状态:', state);
console.log('当前登录用户:', userId);
console.log('设备资源标识:', clientResource);

if (state === 'connected') {
  const restContext = client.getRestContext();
  console.log('REST 访问上下文:', restContext);
}

提示

getConnectionState 返回的是连接状态，不是单独的登录状态。通常可结合 getCurrentUserId 判断当前 SDK 是否已有登录用户。

Token 续期

SDK 会根据当前登录 Token 的过期时间管理 Token 生命周期：

当 Token 即将过期时，SDK 触发 onTokenWillExpire。该事件通常在 Token 生命周期达到约 80% 时触发。
当 Token 已过期时，SDK 触发 onTokenExpired，并断开当前连接。

收到 onTokenWillExpire 后，建议从你的应用服务器获取新的 IM Token，并调用 renewToken 更新 Token。更新成功后，renewToken 返回新的 token 和 expireAt，分别表示当前已生效的 Token 以及 Token 过期时间戳，单位为毫秒。

client.addEventHandler('token-listener', {
  onTokenWillExpire: async () => {
    const newToken = await fetchNewTokenFromServer();
    const result = await client.renewToken(newToken);
    console.log('Token 续期成功，过期时间:', result.expireAt);
  },
  onTokenExpired: () => {
    console.log('Token 已过期，需要重新获取 Token 后登录');
  },
});

renewToken 仅在 SDK 已连接时可调用。若 Token 已过期并触发 onTokenExpired，需要重新获取 Token 后调用 login 登录 SDK。

退出登录

你可以调用 logout 主动退出登录：

await client.logout();

调用 logout 后，SDK 会关闭当前连接，取消正在进行的同步任务，清理当前登录用户、Token、设备资源标识、运行时缓存引用和日志上报状态，并将连接状态更新为 disconnected。如果需要继续使用 IM 能力，需要重新调用 login 登录 SDK。

多设备登录

除了单端单设备登录，即时通讯 IM 支持同一账号在多端的多个设备上登录。多设备登录时，若同端设备数量超过限制，新登录的设备可能会将之前登录的设备踢下线。具体设备数量限制、互踢策略以及信息同步规则，详见多设备登录。

初始化参数控制设备标识

你可以通过以下初始化参数控制设备标识：

参数	类型	描述
`useFixedDeviceId`	Boolean	是否在同一浏览器中复用固定设备标识。默认值为 `true`，同一浏览器中的多个标签页通常视为同一设备；设置为 `false` 时，每个 SDK 实例使用随机设备 ID。
`deviceId`	String	自定义设备标识；未传时使用 SDK 默认值。
`customOSPlatform`	Number	自定义平台编号，取值范围为 1-100，用于区分不同端。
`customDeviceName`	String	自定义设备名称，通常与 `customOSPlatform` 搭配使用。
`loginExtensionInfo`	String	登录自定义扩展信息。当多设备登录策略导致当前设备被踢下线时，可用于传递踢下线相关扩展信息，最大长度为 1024 个字符。

示例代码如下：

const client = ChatClient.init({
  appId: 'easemob-demo#chatdemoui',
  useFixedDeviceId: true,
  customOSPlatform: 10,
  customDeviceName: 'web-custom-device',
  loginExtensionInfo: 'login from web',
});

设备互踢

当多设备登录策略导致当前设备被踢下线时，SDK 会触发 onDisconnected 事件。你可以通过事件回调中的 errorCode 和 errorMessage 判断断开原因，并按业务需要提示用户或引导用户重新登录。

常见多设备相关错误码如下：

场景	错误码 / Key	说明
用户在另一设备登录并踢出当前设备	`206` / `USER_LOGIN_ANOTHER_DEVICE`	通常需要提示用户当前账号已在其他设备登录。
用户因修改密码被踢下线	`216` / `USER_KICKED_BY_CHANGE_PASSWORD`	通常需重新获取 Token 后登录。
用户在其他设备、通过 API 或控制台被强制退出	`217` / `USER_KICKED_BY_OTHER_DEVICE`	可提示用户被强制退出，如需继续使用再重新登录。
登录设备数超过限制	`214` / `AUTH_LOGIN_TOO_MANY_DEVICES`	需先处理设备数限制，不能仅靠重复登录解决。
绑定到其他设备或登录资源变化	`213` / `AUTH_BIND_ANOTHER_DEVICE`，或 `220` / `USER_DEVICE_CHANGED`	通常需要重新登录或引导用户处理设备状态。

获取其他设备登录信息

你可以调用 getSelfIdsOnOtherPlatform 获取当前账号在其他已登录设备上的登录 ID：

const otherDeviceIds = await client.getSelfIdsOnOtherPlatform();
console.log(otherDeviceIds);

userId：当前登录用户的用户 ID。
resource：设备资源标识，也就是当前登录设备的识别号。

例如，登录 ID 为 alice/web_7f3a9c 时，alice 是用户 ID，web_7f3a9c 是该次登录对应的设备资源标识。

接口列表

API	所属模块/类	说明
`login`	`ChatClient`	使用用户 ID 和 Token 登录 SDK。
`getConnectionState`	`ChatClient`	获取当前连接状态。
`getCurrentUserId`	`ChatClient`	获取当前登录用户 ID。
`getClientResource`	`ChatClient`	获取当前连接的设备资源标识。
`getRestContext`	`ChatClient`	获取当前登录会话的 REST 上下文。
`renewToken`	`ChatClient`	为当前登录会话续期 Token。
`logout`	`ChatClient`	退出当前登录会话。
`getSelfIdsOnOtherPlatform`	`ChatClient`	获取当前账号在其他已登录设备上的登录 ID。

登录

# 登录

# 前提条件

# 用户注册

# 创建用户

# 获取用户 token

# 登录

# 获取当前登录状态和信息

# Token 续期

# 退出登录

# 多设备登录

# 接口列表

登录