初始化并登录 IM
更新时间: 2024/07/22 17:14:15
本文提供小程序环境下, NIM 实例初始化以及登录 IM 的详细说明。
前提条件
开始前,请确保:
- 已集成 SDK。
- 已在云信控制台创建应用,获取 App Key。
- 已配置 IM 登录策略。如未配置相应的登录策略,可能导致后续调用登录接口时因无登录权限而报错(状态码:403)。
实现流程
步骤1:准备 Token
登录 IM 需要通过token
进行鉴权。云信提供静态和动态这 2 种 token
类型,您可根据业务需求进行选择。
-
静态
token
:默认为永久有效。如有需要,可通过云信服务端 API 主动刷新 Token。 -
动态
token
:具备时效性,可在生成时设置token
的有效期。
获取静态Token
-
方式1:在控制台获取静态Token
如果您只需要进行简单的体验或者快速测试,那么可以在云信控制台创建测试用的 IM 账号,并获取与该 IM 账号相应的静态
token
。具体参见注册调试用的 IM 账号。获取的静态token可用于下文提及的静态 Token 登录的鉴权。 -
方式2:调用服务端 API 获取静态Token
如果您有正式的生产环境,且您的业务仅需保障基础的用户信息安全,那么需要通过云信 IM 服务端 API 注册 IM 账号,并获取与之相对应的静态
token
。具体参见注册云信 IM 账号。获取的静态token
可用于静态 Token 登录的鉴权
获取动态Token
如果您有正式的生产环境,且您的业务对用户信息安全有较高的要求,可使用动态token
。动态token可用于动态 Token 登录的鉴权。
-
注册云信 IM 账号,获取 IM 账号(
accid
)和静态token
。 -
基于App Key、App Secret 和
accid
,通过约定算法在应用服务端生成动态token
。
步骤2:初始化并登录
开始初始化前,需明确应用采用的 IM 登录方式。不同的登录方式,初始化配置有所差异。
-
创建 NIM 实例,同时配置初始化参数和初始化同步数据,并注册 NIM 实例事件。
v0.11.0 之前,通过 new 创建 NIM 实例。v0.11.0 开始,通过调用
getInstance
方法创建 NIM 实例(单例模式)。-
必传参数
无论是通过 new 还是
getInstance
创建 NIM 实例,采用静态 token 登录时,都需传入如下参数。参数 类型 描述 appKey
string 当前应用的 App Key,一个 App Key 对应一个账号体系 account
string 用户的 IM 账号,即 accid token
string 获取到的静态 token 初始化可选参数及事件说明,参见下文的 NIM 初始化参数与事件。
-
初始化同步配置
创建 NIM 实例时,需配置 NIM 实例需要从云信服务端同步哪些数据。具体配置项,参见
SyncOptions
。
-
-
调用
connect
方法建立 SDK 与云信服务端的长连接,登录 IM。NIM 实例在建立长连接后会发起同步操作,从云信服务端同步漫游消息、离线消息、好友关系等。同步过程中将触发对应的事件,具体参见文末的同步过程事件同步完成后触发
syncdone
事件。
示例代码:
import NIMSDK from 'nim-web-sdk-ng/dist/NIM_MINIAPP_SDK
// 创建实例
const nim = NIMSDK.getInstance({
appkey: 'YOUR_APPKEY',
account: 'YOUR_ACCID',
token: 'YOUR_TOKEN',
debugLevel: 'debug',
lbsUrls: [
"https://lbs.netease.im/lbs/wxwebconf.jsp"
],
linkUrl: "wlnimsc0.netease.im"
});
const eventList = [
'logined',
'multiPortLogin',
'kicked',
'willReconnect',
'disconnect',
'msg',
'syncdone',
'proxyMsg', 'syncRoamingMsgs', 'syncOfflineMsgs',
'syncMyNameCard', 'syncdone', 'sessions', 'updateMyNameCard', 'updateBlackList', 'updateMuteList',
'sysMsg', 'syncSysMsgs', 'syncFriend', 'friends', 'users', 'updateSystemMessages', 'sysMsgUnread', 'pushEvents',
'msgReceipts', 'teamMsgReceipts', 'updateSession',
'teams', 'myTeamMembers',
'createTeam',
'updateTeamMember',
'updateTeam', 'addTeamMembers', 'updateTeamManagers', 'transferTeam', 'removeTeamMembers', 'dismissTeam', 'updateTeamMembersMute',
]
eventList.forEach((key: any) => {
nim.on(key, (res) => {
console.log(`Receive ${key} event:`, res ? JSON.parse(JSON.stringify(res)) : res);
});
})
// then,receive event 'logined'
await nim.connect();
-
创建 NIM 实例,同时配置初始化参数并注册 NIM 实例事件。
v0.11.0 之前,通过 new 创建 NIM 实例。v0.11.0 开始,通过调用
getInstance
方法创建 NIM 实例(单例模式)。-
必传参数
无论是通过 new 还是
getInstance
创建 NIM 实例,采用动态 token 登录时,都需传入如下参数。参数 类型 描述 appKey
string 当前应用的 App Key,一个 App Key 对应一个账号体系 account
string 用户的 IM 账号,即 accid authType
number 采用动态 token
登录时必须传入 1,表示通过动态token
鉴权,动态token
基于 App Secret 计算生成token
string 获取到的动态 token 初始化可选参数及事件说明,参见下文的 NIM 初始化参数与事件。
-
初始化同步配置
创建 NIM 实例时,需配置 NIM 实例需要从云信服务端同步哪些数据。具体配置项,参见
SyncOptions
。
-
-
调用
connect
方法建立 SDK 与云信服务端的长连接,登录 IM。NIM 实例在建立长连接后会发起同步操作,从云信服务端同步漫游消息、离线消息、好友关系等。同步完成后触发
syncdone
事件。
如采用该登录方式,云信服务端不做 IM 登录鉴权,鉴权工作需由指定的第三方服务器(可以是应用服务器)进行。
实现该登录方式,需完成如下操作:
-
实现该登录方式,需提前开通和配置第三方回调服务。
-
创建 NIM 实例,同时配置初始化参数并注册 NIM 实例事件。
v0.11.0 之前,通过 new 创建 NIM 实例。v0.11.0 开始,通过调用
getInstance
方法创建 NIM 实例(单例模式)。-
必传参数
无论是通过 new 还是
getInstance
创建 NIM 实例,通过第三方回调登录时,都需传入如下参数。参数 类型 描述 appKey
string 当前应用的 App Key,一个 App Key 对应一个账号体系 account
string 用户的 IM 账号,即 accid authType
number 登录 IM 的鉴权方式,采用该登录方式时必须传入 2,表示通过第三方回调进行鉴权 token
string 获取到的 token 初始化可选参数及事件说明,参见下文的 NIM 初始化参数与事件。
-
初始化同步配置
创建 NIM 实例时,需配置 NIM 实例需要从云信服务端同步哪些数据。具体配置项,参见
SyncOptions
。
-
-
调用
connect
方法建立 SDK 与云信服务端的长连接,登录 IM。NIM 实例在建立长连接后会发起同步操作,从云信服务端同步漫游消息、离线消息、好友关系等。同步完成后触发
syncdone
事件。 -
发起登录相关回调的请求,由第三方服务器进行鉴权并判定 IM 登录事件是否放行通过。
若不通过,云信服务端将返回 302 错误码。
事件必须在调用 connect
方法前声明才会生效,声明方式可以参考示例代码中 eventList
里的内容。
注意事项
-
如需配置初始化参数
lbsUrls
,请确保只传入一个固定的 LBS 地址。因为实例在小程序环境中运行,会受上文的域名白名单限制,无法使用动态 LBS 服务动态调配长连接地址。 -
微信小程序 1.7.0 及以上版本,最多可同时存在 5 条 WebSocket 连接,其中同域名的 WebSocket 连接最多 2 条。 如需在切换账号或聊天室时使用新实例,为保证不超过WebSocket 连接限制,请务必先调用 NIM / Chatroom 实例的
destroy
方法,并在promise
完成后以后再去创建新的实例。 -
微信小程序初始化时必须设置 LBS 地址,以及默认的连接地址。示例代码如下:
import NIMSDK from 'nim-web-sdk-ng/dist/NIM_MINIAPP_SDK const nim = new NIMSDK({ appkey: "YOUR_APPKEY", token: "YOUR_TOKEN", account: "YOUR_ACCOUNT", lbsUrls: [ "https://lbs.netease.im/lbs/wxwebconf.jsp" ], linkUrl: "wlnimsc0.netease.im" })
更多相关限制信息和已知问题,请参见已知问题及处理建议。
相关信息
同步过程事件
同步过程中会触发如下事件:
事件 | 对应回调 |
---|---|
关系(包括黑名单列表和静音列表) | relations |
好友 | friends |
我的名片 | syncMyNameCard |
好友的名片 | users |
群 | teams |
会话 | sessions |
漫游消息 | syncRoamingMsgs |
离线消息 | syncOfflineMsgs |
离线系统通知 | syncSysMsgs |
更新 NIM 初始化配置
可调用setOptions
方法更新原 SDK 实例的初始化配置,具体参数见下文的NIM 初始化参数与事件。
断网重连机制
SDK 提供了自动重连机制(自动重新建立与云信服务器的连接并重新登录),即将进入重连逻辑会触发事件 willReconnect
。
SDK 在两种场景下会自动进行重连:
- 手动/自动登录成功后,网络不佳导致链接断开的情况。
- 网络不佳时,账号密码本身正常(未被封禁,且账号密码均正确),启动App时调用自动登录接口的情况。
满足上述中一个条件,当用户遇到普通网络问题如连接超时等,会自动进行重连登录,不需要应用上层去做额外的重登逻辑。
jsnim.on('disconnect', function (obj) {
console.log('已断开连接', obj)
})
nim.on('willReconnect', function (obj) {
console.log('收到了重连事件', obj)
})
多端登录与互踢
当前 NIM SDK 支持配置四种不同的 IM 多端登录与互踢策略,具体参见多端登录与互踢。
NIM 初始化参数与事件
点击查看初始化参数与回调
IM 登录相关
参数/事件 |
类型 |
是否必传 | 说明 |
---|---|---|---|
account |
string | 是 | IM 账号(即accid ) |
appKey |
string | 是 | 应用的 App Key,在云信控制台创建应用后获取 |
token |
string | 是 | 校验用户身份的令牌,分为静态 token 和动态 token 两种,只会在建立连接时校验一次 |
authType |
number | 否 | IM 登录的鉴权方式,默认为 0
|
customClientType |
number | 否 | 自定义客户端类型,请设置大于 0 的整数 |
needReconnect |
boolean | 否 | 是否开启自动重连,默认 true,即如果长连接因为网络问题、心跳超时等原因断开,NIM SDK 默认自动尝试重连 onwillreconnect 事件 |
reconnectionAttempts |
boolean | 否 | NIM SDK 尝试重连的最大次数。达到最大重连次数后将不再重连,并触发ondisconnect 回调,表示连接彻底断开 |
lbsUrls |
string[] | 否 | LBS 地址。NIM SDK 需要先请求 LBS 地址,再建立长连接(WebSocket 连接)。若不传此参数,默认将使用云信提供的公网地址。['https://address1', 'https://address2'] |
linkUrl |
string | 否 | WebSocket 备用地址,当 LBS 请求失败时,尝试直接连接 WebSocket 备用地址 |
isFixedDeviceId |
boolean | 否 | 是否需要固定设备 ID,默认 false
|
logined |
- | - | IM 登录成功的事件 |
disconnect |
- | - | NIM 实例与云信服务端断开长连接的事件 |
willReconnect |
- | - | 即将自动重连的事件 |
kicked |
- | - | 被使用相同 IM 账号(accid)登录的其他设备端踢下线的事件 |
multiPortLogin |
- | - | 多个设备端使用相同 IM 账号(accid)登录的事件 |
syncdone |
- | - | 从云信服务端同步数据完成的事件 |
SDK 日志相关
参数 |
类型 |
是否必传 | 说明 |
---|---|---|---|
debugLevel |
string | 否 |
|
消息相关
事件 | 说明 |
---|---|
msg |
在线消息到达事件 |
syncOfflineMsgs |
初始化时从云信服务端同步离线消息的事件 |
syncRoamingMsgs |
初始化时从云信服务端同步漫游消息的事件 |
broadcastMsgs |
广播消息到达事件的事件(在线或者离线同步收到均会触发) |
clearServerHistoryMsgs |
清除历史消息的事件(初始化同步或多端同步触发) |
deleteSelfMsgs |
单向删除某条消息的事件 |
proxyMsg |
代理消息(透传的)到达事件的事件 |
msgReceipts |
消息已读事件,包括单聊和群聊消息 |
系统通知相关
事件 | 说明 |
---|---|
syncSysMsgs |
初始化时从云信服务端同步漫游/离线系统的事件 |
sysMsg |
在线系统通知到达事件的事件 |
updateSystemMessages |
系统通知更新的事件 |
会话相关
事件 | 说明 |
---|---|
sessions |
初始化时从云信服务端同步会话的事件 |
updateSession |
会话更新的事件 |
群组相关
事件 | 说明 |
---|---|
teams |
初始化时从云信服务端同步群组的事件 |
createTeam |
创建群组的事件 |
addTeamMembers |
添加群成员的事件 |
dismissTeam |
群组解散的事件 |
removeTeamMembers |
成员离群的事件,例如成员 A 调用了 leaveTeam 离群,其他成员会收到这个事件 |
teamMsgReceipts |
接收端到群消息已读回执的事件 |
transferTeam |
群组转让的事件 |
updateTeam |
群组信息更新的事件 |
updateTeamManagers |
群管理更新的事件 |
updateTeamMember |
群成员更新的事件 |
updateTeamMembersMute |
群成员静音列表更新的事件 |
myTeamMembers |
当前账户所在的所有高级群中的成员信息变更的事件 |
超大群相关
事件 | 说明 |
---|---|
superTeams |
超大群初始化同步的事件 |
addSuperTeamMembers |
添加超大群成员的事件 |
removeSuperTeamMembers |
移除超大群成员的事件 |
dismissSuperTeam |
超大群解散的事件 |
transferSuperTeam |
超大群转让的事件 |
updateSuperTeam |
超大群更新的事件 |
updateSuperTeamManagers |
超大群管理员更新的事件 |
updateSuperTeamMember |
超大群成员更新的事件 |
updateSuperTeamMembersMute |
超大群成员静列表更新的事件 |
mySuperTeamMembers |
当前账户所在的所有超大群中的成员信息变更的事件 |
用户资料相关
事件 | 说明 |
---|---|
syncMyNameCard |
初始化时从云信服务端同步个人资料的事件 |
users |
初始化时从云信服务端同步其他用户相关资料的事件 |
updateMyNameCard |
个人资料更新的事件 |
好友关系相关
事件 | 说明 |
---|---|
syncFriend |
好友相关资料进行多端同步的事件 |
friends |
好友资料初始化同步的事件 |
relations |
黑名单或静音列表初始化同步的事件 |
updateBlackList |
黑名单更新的事件 |
updateMuteList |
静音列表更新的事件 |
事件订阅相关
事件 | 说明 |
---|---|
pushEvents |
订阅事件的事件 |