IM 即时通讯(增强版)
Web
开发指南

初始化与登录

更新时间: 2023/07/03 14:17:24

圈组是网易云信开发的类 Discord 场景能力模块。在使用圈组的相关能力前,需要先初始化圈组 SDK 并登录圈组。

前提条件

登录圈组前,请确保:

实现流程

步骤1:初始化

创建圈组 SDK 实例并初始化。

示例代码:

const qchat = QChat.getInstance(
  // param1: QChatInitializeOptions
  {
    appkey: '{{YOUR_APP_KEY}}',
    token: '{{YOUR_TOKEN}}',
    account: '{{YOUR_ACCOUNT}}',
    linkAddresses: ['{{YOUR_ADDRESSES}}'],
    debugLevel: 'debug'
    // for more infomation please see the definition of QChatInitializeOptions.
  },
  // param2: QChatOtherOptions
  { 
    qchatChannelConfig: {
      autoSubscribe: true
    },
    cloudStorageConfig: {
      chunkUploadHost: 'https://www.example.com'
    }
    // for more infomation please see the definition of QChatOtherOptions.
  }
)

初始化重要参数

参数
类型
说明
account string 用户的云信 IM 账号(accid
appkey string 在云信控制台获取的 App Key
token string 登录凭证,和云信 IM 账号一起确认用户身份
authType number 登录鉴权方式
  • 0:通过传入静态 token 进行鉴权。静态 token 恒定不变,且默认永久有效,除非主动调用云信服务端 API 刷新 token
  • 1:通过传入动态 token 进行鉴权。动态 token 可设置有效期,因此具备时效性。采用该鉴权方式可有效提升token 破解难度,降低密码泄露风险
  • 2:过云信的第三方回调功能进行鉴权。云信服务端不做 IM 登录鉴权,鉴权工作需由指定的第三方服务器(可以是应用服务器)进行
linkAddress string[] 与圈组服务端的连接地址列表。推荐使用云信服务端 API 获取。也可通过 IM 连接实例里的getQChatAddress方法获取如使用getQChatAddress方法获取连接地址,那么在登录圈组前,必须先登录 IM。
loginExt string 登录自定义字段,用于提交给应用服务端的第三方回调服务进行登录检测
needReconnect boolean 是否需要自动重连
reconnectionAttempts number 重连尝试次数
s3 any AWS s3 实例。针对有出海需求的用户提供 AWS 云存储支持。出海场景下不支持使用 SDK 自带的网易对象存储(NetEase Object Storage,NOS)的文件存储服务。为了不影响 SDK 体积,可注入 AWS s3 实例的模式来做融合存储,示例代码见注入 AWS s3 实例

完整的初始化入参请参见 QChatInitializeOptions

注入 AWS s3 实例

import s3 from 'aws-sdk/clients/s3'

const options = {
  appkey: ''
  account: '',
  token: '',
  s3: s3,
};
const qchat = new QChat(options);

aws-sdk 的安装脚本如下。请使用 2.1059.0 版本。

npm install aws-sdk

步骤2:设置监听事件

可在创建实例后设置监听事件。以下为监听“登录完成”事件的示例代码。

// 初始化-实例设置监听事件
qchat.on('logined', function (loginResult) { console.log(`login done!! ${loginResult}`) })

如果调用 destroy 方法销毁 SDK 实例,所以已设置监听的事件将移除。


部分重要事件如下:

事件 说明
logined 登录完成
willReconnect 即将重连
disconnect 断开连接
multiSpotLogin 多端登录
kicked 被踢下线
syncdone 同步完成
message 收到新消息
messageUpdate 消息有更新
unreadInfo 收到未读标记
systemNotification 收到系统通知
systemNotificationUpdate 系统通知有更新

完整的事件信息请参见 QChatEventInterface


const eventList = [
  'logined', 'willReconnect', 'disconnect', 'multiSpotLogin', 'kicked', 'syncdone',
  'message', 'messageUpdate', 'unreadInfo', 'systemNotification', 'systemNotificationUpdate',
]
eventList.forEach((key: any) => {
  qchat.on(key, (res: any) => {
    console.log(`Receive ${key} : `, res);
  });
})

步骤3:登录

调用login方法登录圈组。

// 实例登录
await qchat.login()

如果authType设置为通过第三方回调登录,那么在调用圈组登录接口后,还需发起圈组登录回调

登录相关

长连接的建立与断开

SDK 提供了如下 4 个方法维护 SDK 实例与云信服务端之间的长连接。

方法 说明
login 建立长连接并登录圈组
logout 登录圈组,并断开长连接。logout 完成后,SDK 实例不会被销毁,可再次掉调用login方法登录
destroy 销毁当前实例,退出登录状态。同时还会断开长连接、移除所有监听事件销毁部分内部变量,并且此实例再也无法调用 login进行登录
kickOtherClients 将当前用户账号登录的其他设备端踢下线,更多相关说明,参见下文的多端登录与互踢

多端登录与互踢

您可通过云信控制台或者接口对多端登录进行管控。

方式1:通过控制台管控

可在云信控制台配置如下多端登录与互踢策略

  • 只允许一端登录
  • 桌面端(PC 与 Web)互踢、移动端(Android 和 iOS )互踢、桌面端与移动端可同时登录。
  • 各端均可以同时登录在线(最多 10 个设备同时在线)

在控制台配置后,可注册kicked事件回调,监听被踢事件。

方式2:通过接口管控

  1. 其他设备端注册多端登录事件回调(MultiSpotLogin)。

  2. 本端调用kickOtherClients方法,将同时登录圈组的其他设备端踢下线。

    结果:

    其他设备端收到MultiSpotLogin事件。收到该事件回调后,建议其他设备端退出登录并切换到登录界面。

kickOtherClients 使用示例
  • 同账号在 A 设备:
const qchat = new QChatSDK({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCOUNT_1',
  token: 'YOUR_TOKEN'
})

qchat.on('kicked', function (kickedReason) {
  console.log('Be kicked cause:', kickedReason)
})

await qchat.login()

  • 同账号在 B 设备:
const qchat = new QChatSDK({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCOUNT_1',
  token: 'YOUR_TOKEN'
})

qchat.on('multiSpotLogin', (result) => {
  const deviceIds = []
  if (Array.isArray(result)) {
    const ids = result.filter(item => item.online && item.deviceId).map(item => item.deviceId)
    deviceIds = deviceIds.concat(ids)
  } else {
    result.online && deviceIds.push(result.deviceId)
  }

  // 1 秒后踢出 A 设备的自己的账号
  setTimeout(() => {
    const result = await qchat.kickOtherClients({
      deviceIds: deviceIds
    })
    deviceIds = []
    console.log('kick success!!', result)
  }, 1000)
})

await qchat.login()
此文档是否对你有帮助?
有帮助
去反馈
  • 前提条件
  • 实现流程
  • 步骤1:初始化
  • 初始化重要参数
  • 注入 AWS s3 实例
  • 步骤2:设置监听事件
  • 步骤3:登录
  • 登录相关
  • 长连接的建立与断开
  • 多端登录与互踢
  • 方式1:通过控制台管控
  • 方式2:通过接口管控