初始化并登录聊天室

更新时间: 2024/05/27 11:17:37

您可参考如下操作流程快速登录聊天室。进行聊天室开发前,必须先实现聊天室 SDK 与服务端聊天室地址的连接(即初始化和登录聊天室)。登录后,您可按需登出或者销毁聊天室实例。

前提条件

实现流程

步骤1:获取聊天室 ID 和地址

  1. 通过 IM 服务端 API 创建聊天室,并记录返回的 roomid(即聊天室 ID)。详情请参见创建聊天室

  2. 通过 IM 服务端 API 获取聊天室地址,调用时需传入创建聊天室时获取的roomid(即聊天室 ID)。详情请参见获取聊天室地址

请保存获取到的聊天室 ID 和聊天室地址,初始化时需要传入。

步骤2:初始化并登录

聊天室登录和 IM 登录的登录逻辑类似,也分为静态 token 登录、动态 token 登录和通过第三方回调登录。此处仅以静态 token 登录为例进行说明。

  1. 创建聊天室实例(当前版本仅支持通过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 方法更新配置。传入的参数会在下一次登录聊天室或重新登录后生效。
  2. 注册聊天室相关事件回调,监听聊天室连接状态及其他事件。具体事件和示例见ChatroomEventInterface

  3. 调用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

相关信息

开通聊天室功能

  1. 在控制台首页应用管理中选择应用,然后单击 IM 即时通讯下的功能配置按钮进入功能配置页。

    image.png
  2. 在顶部选择聊天室页签,开启聊天室功能。

    开启聊天室.png

  3. 阅读并确认信息后,单击确认开启聊天室功能。

聊天室子功能列表说明

需要单独开通的聊天室子功能说明请参考如下表格:

聊天室功能 功能介绍 默认值
聊天室全服广播 发送聊天室内的全服广播消息,所有聊天室都可以收到该消息 默认不开启
聊天室消息回调 聊天室消息第三方回调能力 默认不开启
单用户可创建聊天室数 单个用户可创建的聊天室数量 默认 200 个
聊天室用户进出消息历史存储 聊天室用户进出的消息是否需要存储在历史消息中 默认开启
聊天室用户进出消息系统下发 聊天室用户进出时是否要下发消息 默认不开启
聊天室历史消息天数 聊天室历史消息可存储的时间限制 默认 10 天
聊天室登录策略 设置聊天室用户登录应用服务器或云信服务器的方式 默认静态 token 登录
聊天室多端登录模式 设置用户在不同端的登录模式 默认只允许一端登录
聊天室进出抄送完全对应 登录聊天室过程中因网络异常会出现抄送登录登出不对齐,因此导致状态判断错乱的情况可开启该功能 默认不开启
聊天室自动销毁机制 聊天室支持根据配置策略自动关闭/销毁,减少资源消耗 默认不开启

配置聊天室登录策略

登录策略指应用需要采用的一种或多种登录鉴权方式。云信 SDK 支持以下三种登录方式:

  • 静态 token:用户手动登录聊天室时需传入静态 token。静态 token 默认永久有效,且恒定不变,除非主动调用服务端 API刷新。
  • 动态 token:用户手动登录聊天室时需传入动态 token。动态 token 具备时效性,适用于对于用户信息安全有较高要求的业务场景。
  • 第三方回调:用户手动登录聊天室时的鉴权工作由指定的第三方服务器(可以是应用服务器)进行,云信服务端不做聊天室登录鉴权。选择第三方回调后,请至第三方回调配置进行相关设置。

聊天室登录策略.png

如未选择相应的登录策略,可能导致用户调用登录接口时因无登录权限而报错(状态码:403)。

配置聊天室多端登录模式

云信 SDK 支持配置两种不同的聊天室多端登录模式:

  • 只允许一端登录,Windows、Web、Android、iOS 彼此互踢。同一账号仅允许在一台设备上登录。当该账号在另一台设备上成功登录时,新设备会将旧设备踢下线。
  • 各端均可以同时登录在线。最多可支持10个设备同时在线,在设备数上限内,所有的新设备再次登录,均不会将在线的旧设备踢下线。

聊天室多端登录.png

  • 控制台修改多端互踢的逻辑之后,下次新的设备登录时才会基于新的多端互踢策略进行校验,已经建立连接的设备不会因为策略的修改被强制踢出。
  • 如果某台设备重复登录同一个聊天室,后登录的会将前面的长连接断开,此时会再触发一次进入聊天室的抄送,但是不会触发退出聊天室的抄送。关于进出聊天室(eventType=9)的抄送请参见聊天室成员进出聊天室事件抄送
此文档是否对你有帮助?
有帮助
去反馈
  • 前提条件
  • 实现流程
  • 步骤1:获取聊天室 ID 和地址
  • 步骤2:初始化并登录
  • 注意事项
  • 后续步骤
  • 相关信息
  • 开通聊天室功能
  • 聊天室子功能列表说明
  • 配置聊天室登录策略
  • 配置聊天室多端登录模式