初始化与登录
更新时间: 2024/07/04 13:58:06
本文提供浏览器环境下 NIM 实例初始化以及 IM 登录的详细说明。
前提条件
开始获取实例前,请确保:
- 已集成 SDK。
- 已在云信控制台创建应用,获取 App Key。
- 已注册云信 IM 账号,获取 accid 和 token。
实现流程
步骤1:准备 Token
登录 IM 需要通过token进行鉴权。云信提供静态和动态这 2 种 token 类型,您可根据业务需求进行选择。
-
静态
token:默认为永久有效。如有需要,可通过云信服务端 API 主动刷新 Token。 -
动态
token:具备时效性,可在生成时设置token的有效期。
获取静态Token
-
方式1:在控制台获取静态Token
如果您只需要进行简单的体验或者快速测试,那么可以在云信控制台创建测试用的 IM 账号,并获取与该 IM 账号相应的静态
token。具体参见注册调试用的 IM 账号。获取的静态token可用于下文提及的静态 Token 登录的鉴权。该方式仅 IM 免费版支持。如已升级为 IM 专业版,则需要调用服务端 API 获取静态
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。
步骤3:初始化并登录
开始初始化前,需明确应用采用的 IM 登录方式。不同的登录方式,初始化配置有所差异。
-
通过 NIM.getInstance 创建 NIM 实例,同时配置初始化参数和初始化同步数据,并注册 NIM 实例事件。
-
必传参数
参数 类型 描述 appKeystring 当前应用的 App Key,一个 App Key 对应一个账号体系 accountstring 用户的 IM 账号,即 accid tokenstring 获取到的静态 token 初始化可选参数及事件说明,参见下文的 NIM 初始化参数与事件。
-
初始化同步配置
创建 NIM 实例时,需配置 NIM 实例需要从云信服务端同步哪些数据。具体配置项,参见
SyncOptions。
-
-
调用
connect方法建立 SDK 与云信服务端的长连接,登录 IM。NIM 实例在建立长连接后会发起同步操作,从云信服务端同步漫游消息、离线消息、好友关系等。同步过程中将触发对应的事件,具体参见文末的同步过程事件同步完成后触发
syncdone事件。
jsimport NIMSDK from 'nim-web-sdk-ng/dist/NIM_BROWSER_SDK'
const nim = NIM.getInstance(
/**
* param1: NIMInitializeOptions
*/
{
appkey: 'YOUR_APPKEY',
token: 'YOUR_TOKEN',
account: 'YOUR_ACCOUNT'
},
/**
* param2: NIMOtherOptions
*/
{
/**
* 会话初始化设置
*/
sessionConfig: {
/**
* 用户可以根据应用场景,设置消息是否要计入未读数。
*/
unreadCountFilterFn: function (msg) {
return true
}
},
/**
* 同步初始化设置
*/
syncOptions: {
/**
* 是否同步置顶会话消息
*/
stickTopSessions: true,
/**
* 是否同步用户信息
*/
myInfo: false
}
}
)
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.getInstance 创建 NIM 实例,同时配置初始化参数并注册 NIM 实例事件。
-
必传参数
参数 类型 描述 appKeystring 当前应用的 App Key,一个 App Key 对应一个账号体系 accountstring 用户的 IM 账号,即 accid authTypenumber 采用动态 token登录时必须传入 1,表示通过动态token鉴权,动态token基于 App Secret 计算生成tokenstring 获取到的动态 token 初始化可选参数及事件说明,参见下文的 NIM 初始化参数与事件。
-
初始化同步配置
创建 NIM 实例时,需配置 NIM 实例需要从云信服务端同步哪些数据。具体配置项,参见
SyncOptions。
-
-
调用
connect方法建立 SDK 与云信服务端的长连接,登录 IM。NIM 实例在建立长连接后会发起同步操作,从云信服务端同步漫游消息、离线消息、好友关系等。同步完成后触发
syncdone事件。
示例代码如下:
// 动态token登录
var nim = NIM.getInstance({
debugLevel: "debug", // 日志级别
appkey: 'appkey',
account: 'account',
token: 'token', // 第一次登录填写的token
/**
* 使用动态 token 登录时,必须设置 authType 为 1
*/
authType: 1
})
nim.on('willReconnect', () => {
/**
* 重新从业务服务器获取 token 后,调用 setOptions 设置新的 token
*/
return fetch('https://you_server_api')
.then((res) => {
return res.json()
})
.then((res) => {
nim.setOptions({
token: res.token
})
})
})
nim.connect()
如采用该登录方式,云信服务端不做 IM 登录鉴权,鉴权工作需由指定的第三方服务器(可以是应用服务器)进行。
实现该登录方式,需完成如下操作:
-
实现该登录方式,需提前开通和配置第三方回调服务。
-
通过 NIM.getInstance 创建 NIM 实例,同时配置初始化参数并注册 NIM 实例事件。
-
必传参数
参数 类型 描述 appKeystring 当前应用的 App Key,一个 App Key 对应一个账号体系 accountstring 用户的 IM 账号,即 accid authTypenumber 登录 IM 的鉴权方式,采用该登录方式时必须传入 2,表示通过第三方回调进行鉴权 tokenstring 获取到的 token 初始化可选参数及事件说明,参见下文的 NIM 初始化参数与事件。
-
初始化同步配置
创建 NIM 实例时,需配置 NIM 实例需要从云信服务端同步哪些数据。具体配置项,参见
SyncOptions。
-
-
调用
connect方法建立 SDK 与云信服务端的长连接,登录 IM。NIM 实例在建立长连接后会发起同步操作,从云信服务端同步漫游消息、离线消息、好友关系等。同步完成后触发
syncdone事件。 -
发起登录相关回调的请求,由第三方服务器进行鉴权并判定 IM 登录事件是否放行通过。
若不通过,云信服务端将返回 302 错误码。
事件必须在调用 connect 方法前声明才会生效,声明方式可以参考示例代码中 eventList 里的内容。
相关信息
同步过程事件
同步过程中会触发如下事件:
| 事件 | 对应回调 |
|---|---|
| 关系(包括黑名单列表和静音列表) | 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.getInstance方法进行首次初始化时,配置私有化服务器地址中的 LBS 和长连接域名相关信息。配置详情请参见配置 LBS 和长连接域名 |
| 融合存储 | NIM SDK 默认使用 NOS 做文件存储。若开发者服务的对象是在海外,那么可以通过 SDK 来选择 AWS S3 做融合存储。使用融合存储需要依赖 s3 的 SDK 文件,为了减小 NIM SDK 体积所以需要用户在自己的项目中引入 AWS S3 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 |
订阅事件的事件 |






