初始化与登录

更新时间: 2023/03/28 02:17:37

本文介绍如何初始化 SDK 并完成登录 IM。登录 IM 后才可调用信令相关能力。

前提条件

集成 SDK

实现方法

步骤1:初始化

将 SDK 引入您的项目, 例如引入到 3rd 文件夹下。引入后您需要先完成 SDK 初始化。

初始化示例代码如下:

jsconst NIMSDK = require('../3rd/NIM_MINIAPP_SDK')

const nim = new NIMSDK({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCID',
  token: 'YOUR_TOKEN',
  debugLevel: 'debug',
});

const eventList = [
  'logined', 'multiPortLogin', 'kicked', 'willReconnect', 'disconnect',
]

eventList.forEach((key: any) => {
  nim.on(key, (res) => {
    console.log(`Receive ${key} event:`, res ? JSON.parse(JSON.stringify(res)) : res);
  });
})

const signalingEventList = [
  'signalingClose', 'signalingJoin', 'signalingInvite', 'signalingCancelInvite', 'signalingReject',
  'signalingAccept', 'signalingLeave', 'signalingCustomCommand', 'singalingSyncChannels'
]

signalingEventList.forEach((key: any) => {
  nim.signaling.on(key, (res) => {
    console.log(`Receive ${key} event:`, res ? JSON.parse(JSON.stringify(res)) : res);
  });
})

await nim.connect();

// 把实例挂载到全局而不是作为页面中可被观测的存在,这里简单给个示例
const app = getApp()
app.global.nim = nim

有关于初始化参数和事件,以及其他 API:

SDK 相关事件必须在 connect(登录)前声明才会生效,声明方式可以参考初始化中eventList里的内容。

步骤2:登录 IM

SDK 初始化完成后,调用nim.connect 方法开始建立长连接,发送登录认证协议,并且登录成功进入同步逻辑。在同步完成后, Promise 完成。

jsif (nim.status === 'unconnected') {
  // then,receive event 'logined'
  await nim.connect();
}

相关信息

断网重连

SDK 提供了自动重连机制(自动重新建立与云信服务器的连接并重新登录),即将进入重连逻辑会触发事件 willReconnect

SDK 在两种场景下会自动进行重连:

  • 手动/自动登录成功后,网络不佳导致链接断开的情况。
  • 网络不佳时,账号密码本身正常(未被封禁,且账号密码均正确),启动App时调用自动登录接口的情况。

满足上述中一个条件,当用户遇到普通网络问题如连接超时等,会自动进行重连登录,不需要上层开发者去做额外的重登逻辑。

jsnim.on('disconnect', function (obj) {
  console.log('已断开连接', obj)
})

nim.on('willReconnect', function (obj) {
  console.log('收到了多端登陆通知', obj)
})

多端登录与互踢

云信SDK支持配置多种多端登录策略:

  • 只允许一端登录。

  • 桌面PC与Web端互踢、移动Android和iOS端互踢、桌面与移动端同时登录。

    • 如果SDK相同,互踢。
    • Windows SDK和Web SDK为一类,Android SDK和iOS SDK为另一类,这两类之间,同类互踢,不同类不互踢。
  • 各端均可以同时登录在线(最多10个设备同时在线)。

在收到多端登陆通知后,将会触发 multiPortLogin 事件。

SDK 支持本端主动踢掉其他登录端,参见 NIMInterface-kick

当本端收到了被踢事件,建议回到登陆页,示例代码如下:

jsnim.on('kicked', function () { console.log('被踢') })


const multiDeviceIds = []
nim.on('multiPortLogin', (result) => {
  if (result && result.length > 0) {
    const ids = result.map((item: any) => item.online && item.deviceId)
    multiDeviceIds = multiDeviceIds.concat(ids)
  }
})

async function kick() {
  const result = await nim.kick({
    deviceIds: multiDeviceIds
  })
  multiDeviceIds = []
  console.log('kick success!!')
},

登出/销毁实例

开发者需要自己管理好长连接的实例,不使用可以将其断开或者销毁。

登出或断开实例,参见 TS 定义 NIMInterface-disconnect

对于完全销毁实例,SDK 内部提供了 destrory 方法,方便您做到干净重连。具体说明请参见 TS 定义 NIMInterface-destroy

示例代码如下:

jsconst nim = NIMSDK.getInstance({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCID',
  token: 'YOUR_TOKEN',
  debugLevel: 'debug',
});
await nim.connect()

// 断开
await nim.disconnect()

setTimeout(function() {
  // 断开后仍旧可以 connect 成功
  await nim.connect()

  // 销毁后就无法再次 connect 建立长连接,需要再次 new 一个实例。
  await nim.destroy()
}, 5000)
  • 如果是手动断开连接 nim.disconnect() 后还是可以通过 nim.connect() 恢复连接,而 nim.destroy() 销毁后,无法在恢复连接,只能重新建立实例。

  • 部分平台限制了开发者建立长连接的数量,尤其是 uniapp 只能够建立一条 websocket 连接,所以尽可能销毁前面的实例,自行保证只有一个实例在建立连接。

日志等级

sdk 的初始化参数 debugLevel 提供几种日志等级 "off" | "error" | "warn" | "log" | "debug"

等级 描述
off 关闭日志
error 最高,只打印 error 相关的日志
warn 打印 error、warn 相关的日志
log 打印 error、warn、log 相关的日志
debug 最低,打印 error、warn、log、debug 相关的日志
此文档是否对你有帮助?
有帮助
去反馈
  • 前提条件
  • 实现方法
  • 步骤1:初始化
  • 步骤2:登录 IM
  • 相关信息
  • 断网重连
  • 多端登录与互踢
  • 登出/销毁实例
  • 日志等级