初始化并登录聊天室
更新时间: 2024/05/27 11:17:37
您可参考如下操作流程快速登录聊天室。进行聊天室开发前,必须先实现聊天室 SDK 与服务端聊天室地址的连接(即初始化和登录聊天室)。登录后,您可按需登出或者销毁聊天室实例。
前提条件
- 已注册云信 IM 账号,获取 accid 和 token。
- 已已开通聊天室功能。
- 已配置聊天室登录策略。如未配置相应的登录策略,可能导致后续调用登录接口时因无登录权限而报错(状态码:403)。
实现流程
步骤1:获取聊天室 ID 和地址
-
通过 IM 服务端 API 创建聊天室,并记录返回的
roomid
(即聊天室 ID)。详情请参见创建聊天室。 -
通过 IM 服务端 API 获取聊天室地址,调用时需传入创建聊天室时获取的
roomid
(即聊天室 ID)。详情请参见获取聊天室地址。
请保存获取到的聊天室 ID 和聊天室地址,初始化时需要传入。
步骤2:初始化并登录
聊天室登录和 IM 登录的登录逻辑类似,也分为静态 token 登录、动态 token 登录和通过第三方回调登录。此处仅以静态 token 登录为例进行说明。
-
创建聊天室实例(当前版本仅支持通过
new
创建)并进行初始化。部分重要的初始化参数如下:
参数类型是否必传 描述 appkey
string 是 当前应用的 App Key,一个 App Key 对应一个账号体系 account
string 是 云信 IM 账号(即 accid) token
string 是 验证用户身份的令牌 chatroomId
string 是 聊天室 ID chatroomAddresses
string[] 是 聊天室地址 isAnonymous
boolean 否 以固定成员或游客身份登录聊天室 - false:以固定成员身份登录聊天室
- true:以游客身份匿名登录聊天室。此时必须填写用户昵称(非匿名方式为选填),建议填写头像。第一次使用匿名方式登录聊天室时(新建实例),无需填写
account
参数,但需要在登录以后从聊天室实例中获取 SDK 生成的该参数
- 更多初始化参数参见
ChatroomInitializeOptions
。 - 初始化完成后,若想修改初始化传入的参数,可调用
setOptions
方法更新配置。传入的参数会在下一次登录聊天室或重新登录后生效。
-
注册聊天室相关事件回调,监听聊天室连接状态及其他事件。具体事件和示例见
ChatroomEventInterface
-
调用
connect
方法与聊天室建立连接并登录聊天室。登录成功则触发
logined
事件回调。- 进入聊天室时必须建立新的连接,退出聊天室或者被踢会断开连接。
- 支持建立多个连接,同时进入多个聊天室。
- 当发生掉线时,聊天室 SDK 会自动进行重连。需要监听聊天室连接状态来做出正确的界面表现。
示例代码:
// 创建实例
const chatroom = getInstance({
// ...初始化配置信息
"appkey": "YOUR_APPKEY", // 传入在云信控制台获取的 App Key
"token": "YOUR_TOKEN", // 传入 token
"account": "YOUR_ACCOUNT" // 传入云信 IM 账号(accid)
"isAnonymous": false, // 设置为非匿名模式登录
"chatroomId": "YOUR_CHATROOM_ID", // 传入聊天室 ID
"chatroomAddresses": [
"YOUR_CHATROOM_ADDR"
] // 传入聊天室地址,如传入多个聊天室地址,登录后同时进入这些聊天室
});
const eventList = [
// about login
'logined', 'willReconnect', 'disconnect', 'kicked',
// multi client login notification
'multiPortLogin', ,
// receive chatroom message
'chatroomMsg'
// about tag
'tagsUpdate'
]
eventList.forEach((key: any) => {
chatroom.on(key, (res: any) => {
console.log(`receive ${key} event:`, res);
});
})
await chatroom.connect()
// 当前版本仅支持通过 new 创建实例
const chatroom = getInstance({
// ...初始化配置信息
"appkey": "YOUR_APPKEY",
"token": "YOUR_TOKEN",
"account": "YOUR_ACCOUNT"
"isAnonymous": true,
"chatroomId": "YOUR_CHATROOM_ID",
"chatroomAddresses": [
"YOUR_CHATROOM_ADDR"
],
chatroomNick: 'YOUR_NICK',
chatroomAvatar: 'YOUR_AVATAR',
});
// ...
注意事项
微信小程序 1.7.0 及以上版本,最多可同时存在 5 条 WebSocket 连接,其中同域名的 WebSocket 连接最多 2 条。
如需在切换账号或聊天室时使用新实例,为保证不超过WebSocket 连接限制,请务必先调用 NIM / Chatroom 实例的 destroy
方法,并在 promise
完成后以后再去创建新的实例。
更多相关限制信息和已知问题,请参见已知问题及处理建议。
后续步骤
为保障通信安全,如果您在调试环境中的使用的是云信控制台生成的测试用 IM 账号 和 token
,请确保在后续的正式生产环境中,将其替换为通过 IM 服务端 API 生成的正式 IM 账号(accid
)和 token
。
相关信息
开通聊天室功能
-
在控制台首页应用管理中选择应用,然后单击 IM 即时通讯下的功能配置按钮进入功能配置页。
-
在顶部选择聊天室页签,开启聊天室功能。
-
阅读并确认信息后,单击确认开启聊天室功能。
聊天室子功能列表说明
需要单独开通的聊天室子功能说明请参考如下表格:
聊天室功能 | 功能介绍 | 默认值 |
---|---|---|
聊天室全服广播 | 发送聊天室内的全服广播消息,所有聊天室都可以收到该消息 | 默认不开启 |
聊天室消息回调 | 聊天室消息第三方回调能力 | 默认不开启 |
单用户可创建聊天室数 | 单个用户可创建的聊天室数量 | 默认 200 个 |
聊天室用户进出消息历史存储 | 聊天室用户进出的消息是否需要存储在历史消息中 | 默认开启 |
聊天室用户进出消息系统下发 | 聊天室用户进出时是否要下发消息 | 默认不开启 |
聊天室历史消息天数 | 聊天室历史消息可存储的时间限制 | 默认 10 天 |
聊天室登录策略 | 设置聊天室用户登录应用服务器或云信服务器的方式 | 默认静态 token 登录 |
聊天室多端登录模式 | 设置用户在不同端的登录模式 | 默认只允许一端登录 |
聊天室进出抄送完全对应 | 登录聊天室过程中因网络异常会出现抄送登录登出不对齐,因此导致状态判断错乱的情况可开启该功能 | 默认不开启 |
聊天室自动销毁机制 | 聊天室支持根据配置策略自动关闭/销毁,减少资源消耗 | 默认不开启 |
配置聊天室登录策略
登录策略指应用需要采用的一种或多种登录鉴权方式。云信 SDK 支持以下三种登录方式:
- 静态 token:用户手动登录聊天室时需传入静态 token。静态 token 默认永久有效,且恒定不变,除非主动调用服务端 API刷新。
- 动态 token:用户手动登录聊天室时需传入动态 token。动态 token 具备时效性,适用于对于用户信息安全有较高要求的业务场景。
- 第三方回调:用户手动登录聊天室时的鉴权工作由指定的第三方服务器(可以是应用服务器)进行,云信服务端不做聊天室登录鉴权。选择第三方回调后,请至第三方回调配置进行相关设置。
如未选择相应的登录策略,可能导致用户调用登录接口时因无登录权限而报错(状态码:403)。
配置聊天室多端登录模式
云信 SDK 支持配置两种不同的聊天室多端登录模式:
- 只允许一端登录,Windows、Web、Android、iOS 彼此互踢。同一账号仅允许在一台设备上登录。当该账号在另一台设备上成功登录时,新设备会将旧设备踢下线。
- 各端均可以同时登录在线。最多可支持10个设备同时在线,在设备数上限内,所有的新设备再次登录,均不会将在线的旧设备踢下线。
- 控制台修改多端互踢的逻辑之后,下次新的设备登录时才会基于新的多端互踢策略进行校验,已经建立连接的设备不会因为策略的修改被强制踢出。
- 如果某台设备重复登录同一个聊天室,后登录的会将前面的长连接断开,此时会再触发一次进入聊天室的抄送,但是不会触发退出聊天室的抄送。关于进出聊天室(eventType=9)的抄送请参见聊天室成员进出聊天室事件抄送。