初始化并登录 IM

更新时间: 2024/07/09 15:55:48

集成 NIM SDK 之后,用户需要先调用 SDK 的初始化接口,初始化 SDK 并登录 IM。登录 IM 成功后,用户才能正常调用消息和会话等其他 SDK 接口。

本文介绍实现 IM 初始化和 IM 登录的流程以及相关的示例代码等。

如需初始化和登录聊天室,请参见聊天室集成文档

功能介绍

初始化的同时,NIM SDK 与云信服务端建立长连接(WebSocket 长连接),实现 IM 的首次登录。一旦登录成功后,NIM SDK 将接管所有的重连情况:在网络正常的情况下不停重试重连直到正常登录为止,并不需要做额外的登录操作。

初始化的模块主要包括:

  • IM 消息
  • 会话
  • 用户资料
  • 好友关系
  • 用户关系
  • 群组
  • 超大群

使用限制

  • 微信小程序 1.7.0 及以上版本,最多可同时存在 5 条长连接和最多 2 条同域名的长连接。因此在使用多条长连接时,请务必控制连接数量。可通过销毁实例控制连接数量,具体参见销毁 IM 实例

  • 用户切换账号或者使用新的 IM 实例时,为保证不超过小程序的长连接数量限制,请务必先调用 IM 实例的destroy方法,并在done回调触发后再去发起新的连接。destroy方法的使用说明,参见销毁 IM 实例

前提条件

  • 已集成 SDK。
  • 已在云信控制台创建应用,获取 App Key 和 App Secret。
  • 注册云信 IM 账号,获取 accid 和 token。
  • 已在云信控制台配置应用的 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 登录的鉴权。

  1. 注册云信 IM 账号,获取 IM 账号(accid)和静态token

  2. 基于App Key、App Secret 和accid,通过 约定算法在应用服务端生成动态token

步骤2:初始化并登录

初始化 SDK 实例时,SDK 会同时与云信服务端建立连接,实现 IM 登录。默认的登录方式为静态 Token 登录

初始化方法为NIM.getInstance

NIM.getInstance方法为单例模式, 对于同一个账号, 永远返回同一个实例, 即只在第一次调用时初始化一个实例。后续调用该方法会直接返回初始化过的实例。如需更新初始化配置,不建议继续调用该方法,具体更新方法参见下文的更新初始化配置

登录方式概览

NIM SDK 登录方式分为静态 token 登录、动态 token 登录和通过第三方回调登录。您可按需实现一种或多种登录方式。

静态 token 登录

如需实现静态 token 登录,调用NIM.getInstance方法初始化 SDK 实例时,传入accountappKeytoken这三个必传参数即可。

如果 NIM SDK 与云信服务端建立连接,将触发onconnect回调函数,表示登录 IM 成功。

以下仅列举了部分登录相关的初始化参数,更多初始化参数说明,参见下文的初始化参数

如果您的应用主要服务于海外用户,需在初始化时进行出海配置。具体参见下文的出海配置

参数
类型 是否必传 说明
account string 用户的 IM 账号,即accid
appKey string 当前应用的 App Key,一个 App Key 对应一个账号体系
authType number 登录 IM 的鉴权方式。采用静态token登录时,使用默认的 0 即可,即静态token鉴权
token string 获取到的静态token
onconnect function NIM SDK 与云信服务端建立长连接后的回调函数
若登录成功,可通过该回调获取登录信息
ondisconnect function NIM SDK 与云信服务端的长连接断开后的回调函数
若登录失败,可通过该回调获取失败信息

如下示例代码中的:

  • data代表数据, 后续章节的示例代码中会多次用到该对象。
  • nim代表 SDK 初始化后的 IM 实例,后续章节的示例代码中会多次用到该对象。
var data = {};
// 注意这里, 当引入的SDK文件是NIM_Web_NIM_v.js时,请通过 NIM.getInstance 来初始化;当引入的SDK文件为NIM_Web_SDK_v时,请使用 SDK.NIM.getInstance 来初始化。SDK文件的选择请参见集成方式。
var nim = NIM.getInstance({
  debug: true,   // 是否开启日志,将其打印到console。集成开发阶段建议打开。
  appKey: 'appKey', // 云信控制台获取的 App Key
  account: 'account', // 云信控制台获取或服务端注册的用户账号 accid
  token: 'token', // 云信控制台获取或服务端生成的静态 Token
  db:true, //若不要开启数据库请设置false。SDK默认为true。
  // privateConf: {}, // 私有化部署方案所需的配置
  onconnect: onConnect,
  onwillreconnect: onWillReconnect,
  ondisconnect: onDisconnect,
  onerror: onError
});
function onConnect() {
  console.log('连接成功');
}
function onWillReconnect(obj) {
  // 此时说明 SDK 已经断开连接, 请开发者在界面上提示用户连接已断开, 而且正在重新建立连接
  console.log('即将重连');
  console.log(obj.retryCount);
  console.log(obj.duration);
}
function onDisconnect(error) {
  // 此时说明 SDK 处于断开状态, 开发者此时应该根据错误码提示相应的错误信息, 并且跳转到登录页面
  console.log('丢失连接');
  console.log(error);
  if (error) {
    switch (error.code) {
      // 账号或者密码错误, 请跳转到登录页面并提示错误
      case 302:
        break;
      // 重复登录, 已经在其它端登录了, 请跳转到登录页面并提示错误
      case 417:
        break;
      // 被踢, 请提示错误后跳转到登录页面
      case 'kicked':
        break;
      default:
        break;
    }
  }
}
function onError(error) {
  console.log(error);
}


动态 Token 登录

自 v8.3.0 版本起,NIM SDK 新增动态token登录这一登录方式。动态token具备时效性,可有效提升token破解难度,降低密码泄露风险。

  1. 调用NIM.getInstance方法初始化 SDK 实例并登录 IM 服务端。调用时,除了需要传入accountappKeytoken这三个必传参数,还需要将authType设置为 1

    如果 NIM SDK 与云信服务端建立连接,将触发onconnect回调函数,表示登录 IM 成功。

    以下仅列举了部分登录相关的初始化参数,更多初始化参数说明,参见下文的初始化参数

    如果您的应用主要服务于海外用户,需在初始化时进行出海配置。具体参见下文的出海配置

    参数 类型 是否必传 说明
    account string 用户的 IM 账号,即accid
    authType number 该登录方式必传 采用动态token登录时必须传入 1,表示通过动态token鉴权,动态token基于 App Secret 计算生成
    token string 基于App Secret生成的动态Token
    appKey string 当前应用的 App Key,一个 App Key 对应一个账号体系
    onconnect function NIM SDK 与云信服务端建立长连接后的回调函数
    若登录成功,可通过该回调获取登录信息
    ondisconnect function NIM SDK 与云信服务端的长连接断开后的回调函数
    若登录失败,可通过该回调获取失败信息
    onwillreconnect function NIM SDK 与云信服务端的长连接已断开,而且正在重连时触发的回调函数
  2. onwillreconnect回调函数触发后,调用setOptions方法更新动态token

    // 动态token登录
    var nim = NIM.getInstance({
    debug: true, // 是否开启日志,将其打印到console。集成开发阶段建议打开。
    appKey: 'appKey', // 云信控制台获取的 App Key
    account: 'account', //  云信控制台获取或服务端注册的用户账号 accid
    token: 'token', // 服务端生成的动态 Token
    authType: 1, // 采用动态token登录
    onconnect: onConnect,
    onwillreconnect: onWillReconnect,
    ondisconnect: onDisconnect,
    onerror: onError
    })
    
    function onWillReconnect() {
    nim.setOptions({
        token: 'newToken' // 建议token生成逻辑在客户的服务器侧完成,以免AppSecret泄露。
    })
    }
    

通过第三方回调登录

如采用该登录方式,云信服务端不做 IM 登录鉴权,鉴权工作需由指定的第三方服务器(可以是应用服务器)进行。

实现该登录方式,需完成如下 3 步操作:

  1. 前往云信控制台,并进入IM 即时通讯> 功能配置 > 第三方回调配置第三方回调的环境地址(即第三方服务器地址)和回调失败时放行(通过)与否。

    第三方回调配置文案优化后.png

  2. 调用NIM.getInstance方法初始化 SDK 实例并登录 IM 服务端。调用时,除了需要传入accountappKeytoken这三个必传参数,还需传入authType必须传入 2,且必须传入loginExt

    如果 SDK 与云信服务端建立连接,将触发onconnect回调函数,表示登录 IM 成功。

    • 后续调该方法时, 如果连接已断开, SDK 会自动与云信服务端建立连接。
    • 当发生掉线时,SDK 会自动进行重连。

    以下仅列举了部分登录相关的初始化参数,更多初始化参数说明,参见下文的初始化参数

    如果您的应用主要服务于海外用户,需在初始化时进行出海配置。具体参见下文的出海配置

    参数
    类型 是否必传 说明
    appKey string 当前应用的 App Key,一个 App Key 对应一个账号体系
    account string 用户的 IM 账号,即accid
    authType number 该登录方式必传 登录 IM 的鉴权方式,采用该登录方式时必须传入 2,表示通过第三方回调进行鉴权
    loginExt string 该登录方式必传 登录自定义扩展字段。采用该登录方式时,必须传入,用于第三方服务器鉴权。如未传入,将报错。长度上限为 1k 字符。
    token string 用户自定义 Token
    onconnect function NIM SDK 与云信服务端建立长连接后的回调函数
    若登录成功,可通过该回调获取登录信息
    ondisconnect function NIM SDK 与云信服务端的长连接断开后的回调函数
    若登录失败,可通过该回调获取失败信息
    // 通过第三方回调登录
    var nim = NIM.getInstance({
    debug: true, // 是否开启日志,将其打印到console。集成开发阶段建议打开。
    appKey: 'appKey', // 云信控制台获取的 App Key
    account: 'account', // 云信控制台获取或服务端注册的用户账号 accid
    token: 'token', // 用户自定义 Token
    authType: 2, // 通过第三方回调进行鉴权
    loginExt: 'loginExt', // 登录自定义扩展字段,采用该登录方式时必须传入
    onconnect: onConnect, // NIM SDK 与云信服务端建立长连接后的回调函数若登录成功,可通过该回调获取登录信息
    onwillreconnect: onWillReconnect,
    ondisconnect: onDisconnect, // NIM SDK 与云信服务端的长连接断开后的回调函数若登录失败,可通过该回调获取失败信息
    onerror: onError
    })
    
  3. 发起登录相关回调的请求,由第三方服务器进行鉴权并判定 IM 登录事件是否放行通过。

    若不通过,云信服务端将返回 302 错误码。

相关信息

示例代码

较完整的初始化与登录的示例代码(仅以静态 token 登录为例)

如下示例代码中的:

  • data代表数据, 后续章节的示例代码中会多次用到该对象。
  • nim代表 SDK 初始化后的 IM 实例,后续章节的示例代码中会多次用到该对象。
    var data = {};
    var nim = NIM.getInstance({
        // 初始化SDK
        // debug: true
        appKey: 'appKey',
        account: 'account',
        token: 'token',
        customTag: 'TV',
        onconnect: onConnect,
        onerror: onError,
        onwillreconnect: onWillReconnect,
        ondisconnect: onDisconnect,
        // 多端登录
        onloginportschange: onLoginPortsChange,
        // 用户关系
        onblacklist: onBlacklist,
        onsyncmarkinblacklist: onMarkInBlacklist,
        onmutelist: onMutelist,
        onsyncmarkinmutelist: onMarkInMutelist,
        // 好友关系
        onfriends: onFriends,
        onsyncfriendaction: onSyncFriendAction,
        // 用户名片
        onmyinfo: onMyInfo,
        onupdatemyinfo: onUpdateMyInfo,
        onusers: onUsers,
        onupdateuser: onUpdateUser,
        // 群组
        onteams: onTeams,
        onsynccreateteam: onCreateTeam,
        onUpdateTeam: onUpdateTeam,
        // onsyncteammembersdone: onSyncTeamMembersDone,
        onupdateteammember: onUpdateTeamMember,
        // 群消息业务已读通知
        onTeamMsgReceipt: onTeamMsgReceipt,
        // 会话
        onsessions: onSessions,
        onupdatesession: onUpdateSession,
        // 消息
        onroamingmsgs: onRoamingMsgs,
        onofflinemsgs: onOfflineMsgs,
        onmsg: onMsg,
        // 系统通知
        onofflinesysmsgs: onOfflineSysMsgs,
        onsysmsg: onSysMsg,
        onupdatesysmsg: onUpdateSysMsg,
        onsysmsgunread: onSysMsgUnread,
        onupdatesysmsgunread: onUpdateSysMsgUnread,
        onofflinecustomsysmsgs: onOfflineCustomSysMsgs,
        oncustomsysmsg: onCustomSysMsg,
        // 收到广播消息
        onbroadcastmsg: onBroadcastMsg,
        onbroadcastmsgs: onBroadcastMsgs,
        // 同步完成
        onsyncdone: onSyncDone
    });

    function onConnect() {
        console.log('连接成功');
    }
    function onWillReconnect(obj) {
        // 此时说明 `SDK` 已经断开连接, 请开发者在界面上提示用户连接已断开, 而且正在重新建立连接
        console.log('即将重连');
        console.log(obj.retryCount);
        console.log(obj.duration);
    }
    function onDisconnect(error) {
        // 此时说明 `SDK` 处于断开状态, 开发者此时应该根据错误码提示相应的错误信息, 并且跳转到登录页面
        console.log('丢失连接');
        console.log(error);
        if (error) {
            switch (error.code) {
            // 账号或者密码错误, 请跳转到登录页面并提示错误
            case 302:
                break;
            // 被踢, 请提示错误后跳转到登录页面
            case 'kicked':
                break;
            default:
                break;
            }
        }
    }
    function onError(error) {
        console.log(error);
    }

    function onLoginPortsChange(loginPorts) {
        console.log('当前登录账号在其它端的状态发生改变了', loginPorts);
    }

    function onBlacklist(blacklist) {
        console.log('收到黑名单', blacklist);
        data.blacklist = nim.mergeRelations(data.blacklist, blacklist);
        data.blacklist = nim.cutRelations(data.blacklist, blacklist.invalid);
        refreshBlacklistUI();
    }
    function onMarkInBlacklist(obj) {
        console.log(obj);
        console.log(obj.account + '被你在其它端' + (obj.isAdd ? '加入' : '移除') + '黑名单');
        if (obj.isAdd) {
            addToBlacklist(obj);
        } else {
            removeFromBlacklist(obj);
        }
    }
    function addToBlacklist(obj) {
        data.blacklist = nim.mergeRelations(data.blacklist, obj.record);
        refreshBlacklistUI();
    }
    function removeFromBlacklist(obj) {
        data.blacklist = nim.cutRelations(data.blacklist, obj.record);
        refreshBlacklistUI();
    }
    function refreshBlacklistUI() {
        // 刷新界面
    }
    function onMutelist(mutelist) {
        console.log('收到静音列表', mutelist);
        data.mutelist = nim.mergeRelations(data.mutelist, mutelist);
        data.mutelist = nim.cutRelations(data.mutelist, mutelist.invalid);
        refreshMutelistUI();
    }
    function onMarkInMutelist(obj) {
        console.log(obj);
        console.log(obj.account + '被你' + (obj.isAdd ? '加入' : '移除') + '静音列表');
        if (obj.isAdd) {
            addToMutelist(obj);
        } else {
            removeFromMutelist(obj);
        }
    }
    function addToMutelist(obj) {
        data.mutelist = nim.mergeRelations(data.mutelist, obj.record);
        refreshMutelistUI();
    }
    function removeFromMutelist(obj) {
        data.mutelist = nim.cutRelations(data.mutelist, obj.record);
        refreshMutelistUI();
    }
    function refreshMutelistUI() {
        // 刷新界面
    }

    function onFriends(friends) {
        console.log('收到好友列表', friends);
        data.friends = nim.mergeFriends(data.friends, friends);
        data.friends = nim.cutFriends(data.friends, friends.invalid);
        refreshFriendsUI();
    }
    function onSyncFriendAction(obj) {
        console.log(obj);
        switch (obj.type) {
        case 'addFriend':
            console.log('你在其它端直接加了一个好友' + obj.account + ', 附言' + obj.ps);
            onAddFriend(obj.friend);
            break;
        case 'applyFriend':
            console.log('你在其它端申请加了一个好友' + obj.account + ', 附言' + obj.ps);
            break;
        case 'passFriendApply':
            console.log('你在其它端通过了一个好友申请' + obj.account + ', 附言' + obj.ps);
            onAddFriend(obj.friend);
            break;
        case 'rejectFriendApply':
            console.log('你在其它端拒绝了一个好友申请' + obj.account + ', 附言' + obj.ps);
            break;
        case 'deleteFriend':
            console.log('你在其它端删了一个好友' + obj.account);
            onDeleteFriend(obj.account);
            break;
        case 'updateFriend':
            console.log('你在其它端更新了一个好友', obj.friend);
            onUpdateFriend(obj.friend);
            break;
        }
    }
    function onAddFriend(friend) {
        data.friends = nim.mergeFriends(data.friends, friend);
        refreshFriendsUI();
    }
    function onDeleteFriend(account) {
        data.friends = nim.cutFriendsByAccounts(data.friends, account);
        refreshFriendsUI();
    }
    function onUpdateFriend(friend) {
        data.friends = nim.mergeFriends(data.friends, friend);
        refreshFriendsUI();
    }
    function refreshFriendsUI() {
        // 刷新界面
    }

    function onMyInfo(user) {
        console.log('收到我的名片', user);
        data.myInfo = user;
        updateMyInfoUI();
    }
    function onUpdateMyInfo(user) {
        console.log('我的名片更新了', user);
        data.myInfo = NIM.util.merge(data.myInfo, user);
        updateMyInfoUI();
    }
    function updateMyInfoUI() {
        // 刷新界面
    }
    function onUsers(users) {
        console.log('收到用户名片列表', users);
        data.users = nim.mergeUsers(data.users, users);
    }
    function onUpdateUser(user) {
        console.log('用户名片更新了', user);
        data.users = nim.mergeUsers(data.users, user);
    }
    function onTeams(teams) {
        console.log('群列表', teams);
        data.teams = nim.mergeTeams(data.teams, teams);
        onInvalidTeams(teams.invalid);
    }
    function onInvalidTeams(teams) {
        data.teams = nim.cutTeams(data.teams, teams);
        data.invalidTeams = nim.mergeTeams(data.invalidTeams, teams);
        refreshTeamsUI();
    }
    function onCreateTeam(team) {
        console.log('你创建了一个群', team);
        data.teams = nim.mergeTeams(data.teams, team);
        refreshTeamsUI();
    }
    function refreshTeamsUI() {
        // 刷新界面
    }
    // function onSyncTeamMembersDone() {
    //     console.log('同步群列表完成');
    // }
    function onUpdateTeam (team) {
        console.log('群状态更新', team)
    }
    function onUpdateTeamMember(teamMember) {
        console.log('群成员信息更新了', teamMember);
    }
    function refreshTeamMembersUI() {
        // 刷新界面
    }
    function onTeamMsgReceipt (teamMsgReceipts) {
        console.log('群消息已读通知', teamMsgReceipts)
    }

    function onSessions(sessions) {
        console.log('收到会话列表', sessions);
        data.sessions = nim.mergeSessions(data.sessions, sessions);
        updateSessionsUI();
    }
    function onUpdateSession(session) {
        console.log('会话更新了', session);
        data.sessions = nim.mergeSessions(data.sessions, session);
        updateSessionsUI();
    }
    function updateSessionsUI() {
        // 刷新界面
    }

    function onRoamingMsgs(obj) {
        console.log('漫游消息', obj);
        pushMsg(obj.msgs);
    }
    function onOfflineMsgs(obj) {
        console.log('离线消息', obj);
        pushMsg(obj.msgs);
    }
    function onMsg(msg) {
        console.log('收到消息', msg.scene, msg.type, msg);
        pushMsg(msg);
    }
    function onBroadcastMsg(msg) {
        console.log('收到广播消息', msg);
    }
    function onBroadcastMsgs(msgs) {
        console.log('收到广播消息列表', msgs);
    }
    function pushMsg(msgs) {
        if (!Array.isArray(msgs)) { msgs = [msgs]; }
        var sessionId = msgs[0].sessionId;
        data.msgs = data.msgs || {};
        data.msgs[sessionId] = nim.mergeMsgs(data.msgs[sessionId], msgs);
    }

    function onOfflineSysMsgs(sysMsgs) {
        console.log('收到离线系统通知', sysMsgs);
        pushSysMsgs(sysMsgs);
    }
    function onSysMsg(sysMsg) {
        console.log('收到系统通知', sysMsg)
        pushSysMsgs(sysMsg);
    }
    function onUpdateSysMsg(sysMsg) {
        pushSysMsgs(sysMsg);
    }
    function pushSysMsgs(sysMsgs) {
        data.sysMsgs = nim.mergeSysMsgs(data.sysMsgs, sysMsgs);
        refreshSysMsgsUI();
    }
    function onSysMsgUnread(obj) {
        console.log('收到系统通知未读数', obj);
        data.sysMsgUnread = obj;
        refreshSysMsgsUI();
    }
    function onUpdateSysMsgUnread(obj) {
        console.log('系统通知未读数更新了', obj);
        data.sysMsgUnread = obj;
        refreshSysMsgsUI();
    }
    function refreshSysMsgsUI() {
        // 刷新界面
    }
    function onOfflineCustomSysMsgs(sysMsgs) {
        console.log('收到离线自定义系统通知', sysMsgs);
    }
    function onCustomSysMsg(sysMsg) {
        console.log('收到自定义系统通知', sysMsg);
    }

    function onSyncDone() {
        console.log('同步完成');
    }

更新 IM 初始化配置

可调用setOptions方法更新原 SDK 实例的初始化配置,可配置的参数与NIM.getInstance方法可配置的参数相同,具体见下文的初始化参数

以更新静态 token 为例:

javascript// 断开 IM
nim.disconnect();
// 更新 token
nim.setOptions({
    token: 'newToken'
});
// 重新连接
nim.connect();

出海配置

配置项 说明
海外数据中心 如果你的应用主要服务于海外用户,且数据需要写入海外数据中心,请先在云信控制台选择服务区域为海外,并在调用NIM.getInstance方法进行首次初始化时,配置私有化服务器地址中的 LBS 和 link 域名相关信息。配置详情请参见配置 LBS 和 Link 域名
融合存储 NIM SDK 默认使用 NOS 做文件存储。若开发者服务的对象是在海外,那么可以通过 SDK 来选择 S3 做融合存储。使用融合存储需要依赖 s3 的 SDK 文件,为了减小 NIM SDK 体积所以需要用户在自己的项目中引入 S3 SDK 并在初始化 IM 时注入,否则无法开启融合存储功能。具体如何开启融合存储,请参考融合存储方案

多端登录与互踢

当前 NIM SDK 支持配置四种不同的 IM 多端登录与互踢策略,具体参见多端登录与互踢

初始化参数

点击查看初始化配置说明
初始化配置在 NIMGetInstanceOptions 中定义, 初始化配置可分为如下几类:

登录初始化参数

参数
类型
是否必传 说明
account string IM 账号(即accid
appKey string 应用的 App Key,在云信控制台创建应用后获取
authType number IM 登录的鉴权方式,默认为 0
  • 0:通过静态token鉴权,token 恒定不变,除非主动调用服务端 API 刷新
  • 1:通过动态token鉴权,动态token基于 App Secret 生成,可在生成时指定动态token的过期时间
  • 2:通过第三方回调,由开发者指定的第三方服务器进行 IM 登录的鉴权,云信服务端仅负责在收到 IM 登录请求后将登录信息转发至开发者服务器,并返回第三方服务器的鉴权结果
token string 验证用户身份的令牌,只会在建立连接时校验一次
loginExt string 登录自定义扩展字段,可转发给指定的第三方服务器,不会同步至其他端。长度上限为 1k 字符。authType为 2,即通过第三方回调进行 IM 登录鉴权时,必须传入,用于第三方服务器鉴权。
customClientType string 自定义客户端类型,请设置大于 0 的整数默认端类型只有 Web,PC,android,iOS,如果开发者需要加以更细致的类型区分,如微信小程序等环境,可用这个字段自行做映射。
needReconnect boolean 是否开启自动重连,默认 true,即如果长连接因为网络问题、心跳超时等原因断开,NIM SDK 默认自动尝试重连 重连的时间间隔从 1.6~8s 之间累加,每次重连将触发onwillreconnect事件
quickReconnect boolean 是否开启快速自动重连,默认 false。若设置为 true,NIM SDK 会监听浏览器的 offline 和 online 事件来嗅探网络断开和恢复,将会做相应的断开和重连策略只有当 needReconnect为 true 时该配置才有效。
reconnectionAttempts number NIM SDK 尝试重连的最大次数。达到最大重连次数后将不再重连,并触发ondisconnect回调,表示连接彻底断开
customTag string 客户端自定义 tag。最大 32 个字符
defaultLink string 默认的备用长连接地址。当 LBS 请求出错时,NIM SDK 会尝试该长连接地址,若不传此参数,默认使用云信的公网的备用地址。
lbsUrl string 默认的 LBS 地址。NIM SDK 需要先请求 LBS 地址能得到长连接地址,再建立长连接。若不传此参数,默认将使用云信提供的公网地址。
lbsBackup boolean 是否开启备用 LBS 地址,默认为 true,即 NIM SDK 会将上一次连接成功过的 LBS 地址存储到浏览器本地缓存作为备用,当主 LBS 不可用时,会尝试请求备用 LBS 地址连接
lbsBackupUrlsCustomer string[] 自定义的备用 LBS 地址数组,用于自定义接口去代理 LBS 返回,防止运营商劫持。当主 LBS 不可用且浏览器本地缓存的备用 LBS 地址均不可用时,NIM SDK 会尝试请求自定义的备用 LBS 。示例:['https://address1', 'https://address2']
onconnect function - NIM SDK 与云信服务端建立长连接后的回调函数,原型:onconnect(data: NIMOnConnectResult): void
ondisconnect function - NIM SDK 与云信服务端的长连接断开后的回调函数,原型:ondisconnect(data: NIMOnDisconnectResult): void
onwillreconnect function - 即将重连时触发的回调函数。如果触发,说明 NIM SDK 已与云信服务端断开连接,建议在界面上提示用户:连接已断开,正在重新建立连接
onerror function - 出现错误的回调,这里的“错误”通常为数据库错误,也可能是连接错误
onpushevents function - 用户在线或初始化同步时,用于接收下推的事件服务的回调函数。原型:onpushevents(result: { msgEvents: NIMPushEventInfo[] }): void
onsyncdone function - 初始化同步完成的回调函数。推荐在初始化同步完成后再调用 SDK 实例的接口
onloginportschange function - 多端登录状态变化的回调函数,用户可通过该回调函数获取登录端列表。原型:onloginportschange(datas: NIMOnLoginPortsChangeResult[]): void。以下情况会触发该回调函数:
  • 登录时已有其它设备端在线
  • 登录后其他设备端上线或下线

系统通知初始化参数

参数
类型
是否必传 说明
onsysmsg function - 用于在线时接收系统通知的回调函数。原型:onsysmsg(data: NIMSystemMessage): void
onupdatesysmsg function - 用于在线时接收系统通知更新的回调函数。触发的条件包括通过或拒绝好友申请、接收或拒绝入群申请,以及通过或者拒绝入群邀请。原型:onupdatesysmsg(data: NIMSystemMessage): void
oncustomsysmsg function - 用户在线时,用于接收自定义系统通知的回调函数。原型:oncustomsysmsg(data: NIMSystemMessage): void自定义系统消息不存本地数据库,NIM SDK 直接将自定义系统通知回调透传给上层应用。
onofflinecustomsysmsgs function - 初始化同步时,用于接收离线的自定义系统通知的回调函数。原型:onofflinecustomsysmsgs(datas: NIMSystemMessage[]): void自定义系统消息不存本地数据库,NIM SDK 直接将自定义系统通知回调透传给上层应用。
onofflinesysmsgs function - 初始化同步时,用于接收离线的系统通知的回调函数。原型:onofflinesysmsgs(datas: NIMSystemMessage[]): void
onroamingsysmsgs function - 初始化同步时,用于接收漫游系统通知的回调函数。原型:onroamingsysmsgs(datas: NIMSystemMessage[]): void
onsysmsgunread function - 用于在初始化同步时接收系统通知未读数的回调函数。原型:onsysmsgunread(data: NIMSystemMessageUnreadInfo): void该函数获取的是设备端本地维护的未读数,只统计本次登录期间内接收到的未读数。
onupdatesysmsgunread function - 用于在线时接收系统通知未读数变更。原型:onupdatesysmsgunread(data: NIMSystemMessageUnreadInfo): void 该函数获取的是设备端本地维护的未读数,只统计本次登录期间内接收到的未读数。

数据同步配置

参数
类型
是否必传 说明
syncBroadcastMsgs boolean 是否同步离线广播,默认 false。若同步,初始化同步结束后收到 onbroadcastmsgs 回调
syncExtraTeamInfo boolean 是否同步额外的群信息, 默认 true。若同步,则初始化同步接收群列表的额外信息,结束后收到 onteams 回调这里的“额外信息”举个例子,当前登录用户开启某个群的消息提醒 (SDK 只是存储了此信息, 具体用此信息来做什么事情完全由开发者控制),开发者调用接口 updateInfoInTeam 来设置。
syncFriendUsers boolean 是否同步好友对应的用户名片列表, 默认 true。若同步,则初始化同步接收好友所对应的用户信息,结束后收到 onusers 回调
syncFriends boolean 是否同步好友列表, 默认 true。若同步,则初始化同步接收好友信息,结束后收到 onfriends 回调
syncMsgReceipts boolean 是否同步已读回执时间戳, 默认 true
syncRelations boolean 是否同步黑名单和静音列表, 默认true。若同步,则初始化同步接收黑名单和静音列表,结束后收到 onblacklist 回调和 onmutelist 回调
syncRoamingMsgs boolean 是否同步漫游消息, 默认 true。若同步,则初始化同步结束后收到 onroamingmsgs 回调
syncSessionUnread boolean 是否同步会话的未读数, 默认 false。未读数即会话(session)的 unread 属性
syncStickTopSessions boolean 是否同步云端置顶会话信息,默认 false。初始化同步云端置顶会话信息可以通过 onStickTopSessions 回调获取,且附带在 session 定义的 isTop 属性中
syncSuperTeamRoamingMsgs boolean 是否额外同步超大群的漫游消息, 默认 true。若同步,则初始化同步结束后收到 onroamingmsgs 回调
syncSuperTeams boolean 是否同步超大群列表, 默认true。若同步,则初始化同步接收超级群列表,结束后收到 onSuperTeams 回调
syncTeams boolean 是否同步群列表, 默认 true。若同步,则初始化同步接收群列表,结束后收到 onteams 回调

数据库配置

参数
类型
是否必传 说明
db boolean 是否使用 IM 业务数据库(采用 indexedDb),默认 true。在移动端的 safari 浏览器中,使用 SDK 操作数据库时存在一些异常问题,因此 SDK 在移动端 safari 上禁用了数据库。建议移动端浏览器使用 Web SDK 时默认不开启数据库,在初始化时将db设置为 false在支持数据库的浏览器上,SDK 会将消息、会话、群组等数据缓存到 indexedDB 数据库中, 后续同步都是增量更新, 加快初始化同步速度。
dbLog boolean 是否将日志存储到本地数据库,默认 true,即默认将日志存储到本地数据库。后续如需拉取本地数据库中的日志,请联系云信技术支持 日志数据库与 IM 业务数据库为两个数据库,互不影响

日志配置

参数
类型
是否必传 说明
logLevel "debug" | "log" | "info" | "warn" | "error" | "off" 日志级别,默认 off,即不输出任何日志。设置对应的日志等级后,仅输出高于或等于对应等级的日志
expire number 本地数据库中的日志的有效期,单位:小时,默认 72 小时,仅在dbLog为 true 时生效
logFunc function - 是否对日志做额外的处理,诸如日志存储、日志上报等等,该函数会截获console日志的参数。原型:logFunc(...args: (string | NIMStrAnyObj)[]): void

消息初始化参数

参数
类型
是否必传 说明
onmsg function - 用户在线或多端同步时,用于接收消息的回调函数。原型:onmsg(data: NIMMessage): void
onofflinemsgs function - 初始化同步时,用于接收离线消息的回调函数。原型:onofflinemsgs(datas: NIMMessage[]): void
onDeleteMsgSelf function - 多端同步时消息单向删除的回调函数,原型:`onDeleteMsgSelf(data: NIMOnDeleteMsgSelfResult): void
onbroadcastmsg function - 用户在线时,用于接收广播消息的回调函数。原型:onbroadcastmsg(data: NIMBroadcastMessage): void
onbroadcastmsgs function - 初始化同步时,用于接收广播消息的回调函数。原型:onbroadcastmsgs(datas: NIMBroadcastMessage[]): void
onroamingmsgs function - 初始化同步时,用于接收漫游消息的回调函数。原型:onroamingmsgs(datas: NIMMessage[]): void初始化同步会触发多次这个事件,每一个会话触发一次。
onMsgReceipts function - 在线时,P2P消息标记已读回执的回调函数。

消息扩展配置

参数
类型
是否必传 说明
onQuickComment function - 在线或多端同步时,添加快捷评论的回调函数,原型:onQuickComment(data: Pick<NIMMessage, "scene" | "from" | "time" | "idServer" | "idClient">, comment: NIMQuickComment): void
onDeleteQuickComment function - 在线或多端同步时,删除快捷评论的回调函数,原型:onDeleteQuickComment(data: Pick<NIMMessage, "scene" | "from" | "time" | "idServer" | "idClient">, comment: NIMQuickComment): void
onPinMsgChange function - 在线或多端同步时,更新 PIN 消息的回调函数,原型:onPinMsgChange(data: NIMOnPinMsgChangeResult, action: "add" | "update" | "delete"): void

会话初始化参数

参数
类型
是否必传 说明
autoMarkRead boolean 是否自动标记消息为已收到,默认为 true
resetUnreadMode boolean 重置会话未读数时,若同步至服务器失败,是否仅重置本地会话未读数,默认 true,即本地未读数会被重置,服务端和其他端的未读数不会重置;若为 false,则本地、服务器和其他端都不会被重置(重置失败),各端未读数会保持一致
rollbackClearMsgsUnread boolean 清除会话的消息时是否同时更新会话的未读数与最近一条消息,默认 true
rollbackDelMsgUnread boolean 撤回消息后是否更新该消息所属会话的未读数,默认 false。例子:假设某会话有两条消息未读,其中一条消息被撤回了,此时如果该参数为 true,则会话未读数变为 1,否则未读数仍是 2
shouldCountNotifyUnread function 钩子函数,用于判定通知消息是否计入会话未读数。默认都返回 false。接收一条通知消息,如果该函数结果返回 true,则该通知消息计入未读数,否则不计入未读数。原型:shouldCountNotifyUnread(notification: NIMMessage): void
shouldIgnoreNotification function 钩子函数,用于判定接收到通知消息时是否不更新会话。默认都返回 false。如过返回 true,则将该通知消息计入未读数,否则不计入。原型:shouldIgnoreNotification(notification: NIMMessage): void
onsessions function - 初始化同步时,用于获取会话列表的回调函数。原型:onsessions(datas: NIMSession[]): void
onClearServerHistoryMsgs function - 多端同步或初始化同步时监听会话历史消息的清除事件,需传入被删除的会话的 ID(sessionId以及删除时间),原型:onClearServerHistoryMsgs(data: { sessionId: string; time: number }): void
onSessionsWithMoreRoaming function - 初始化同步时,如果会话仍有更多的漫游消息,将触发该回调函数,原型:onSessionsWithMoreRoaming(datas: NIMSession[]): void其中的 session.time 之前的时间里,仍有超过漫游数量限制而为未漫游下来的消息。可在进入会话时,通过获取历史消息接口再拉取消息
onStickTopSessions function - 初始化同步或在线时,远端会话置顶的回调函数,原型:onStickTopSessions(datas: NIMSession[]): void
onSyncUpdateServerSession function - 多端同步时,服务端会话更新的回调函数,原型:onSyncUpdateServerSession(data: NIMCloudSession): void
onupdatesessions function - 批量更新会话的回调函数。触发条件包括收发消息、清理会话未读数、撤回消息等。原型:onupdatesessions(datas: NIMSession[]): voidv8.2.0 版本开始支持该回调函数

NOS云存储参数

参数
类型
是否必传 说明
nosScenes string 上传文件存储全局配置-存储场景相当于使用的网易云存储的桶名,默认 “im”。
nosSurvivalTime number 上传文件存储全局配置-存储有效时间默认 Infinity,设置的时间不得小于一天,单位:秒。

群组初始化参数

参数
类型
是否必传 说明
onteams function - 用于在初始化同步时获取群列表的回调函数。原型:onteams(datas: NIMTeam[]): void
onCreateTeam function - 在线或多端同步时,创建群组的回调函数,通过该回调函数监听“创建群的通知”,原型:onCreateTeam(data: NIMTeam): void
onDismissTeam funciton - 在线或多端同步时,解散群组的回调函数,通过该回调函数监听“解散群的通知”,原型:onDismissTeam(data: { teamId: string }): void
onupdateteammember function - 用于在线或多端同步时接收群成员信息变更的回调函数。 原型:onupdateteammember(data: Pick<NIMTeamMember, "custom" | "teamId" | "updateTime" | "account" | "id" | "muteNotiType" | "muteTeam" | "nickInTeam">): void
onRemoveTeamMembers function - 在线或多端同步时,删除群成员的回调函数,通过该回调函数接收删除群成员的通知,原型:onRemoveTeamMembers(data: NIMOnRemoveTeamMembersResult): void 您需要判定dataaccount 是否包含当前 IM 账号, 来处理本账号被踢出群的情况。
onTeamMsgReceipt function - 在线时,群消息标记已读回执的回调函数,原型:onTeamMsgReceipt(data: NIMOnTeamMsgReceiptResult): void
onTransferTeam function - 转让群的回调函数,用于在用户在线或多端同步时,接收转让群的通知。原型: onTransferTeam(data: NIMOnTransferTeamResult): void
onUpdateTeam function - 更新群的回调函数,用户在在线或多端同步时,通过该回调函数接收更新群的通知。原型:onUpdateTeam(data: Pick<NIMTeam, "custom" | "announcement" | "avatar" | "intro" | "name" | "teamId" | "updateTime">): void
onUpdateTeamManagers function - 更新群管理员的回调函数,用户在线或多端同步时,通过该回调函数接收更新群管理员的通知。原型:`onUpdateTeamManagers(data: NIMOnUpdateTeamManagersResult): void
onUpdateTeamMembersMute function - 群成员被禁言的回调函数,用户在线或多端同步时,通过该回调函数接收群成员被禁言的通知。原型:onUpdateTeamMembersMute(data: NIMOnUpdateTeamMembersMuteResult): void
onsynccreateteam function - 用于在多端同步时接收创建群的通知的回调函数。原型:onsynccreateteam(data: NIMTeam): void。该回调函数触发后,将触发onCreateTeam
onMyTeamMembers function - 获取自己在所有高级群中的用户信息的回调函数。

超大群初始化参数

参数
类型
是否必传 说明
onSuperTeams?:function function - 初始化同步时,获取超大群列表的回调函数,原型:onSuperTeams(datas: NIMSuperTeam[]): void
onSyncCreateSuperTeam function - 多端同步时,获取创建超大群的通知的回调函数,原型:onSyncCreateSuperTeam(datas: NIMSuperTeam[]): void
onAddSuperTeamMembers function - 在线或多端同步时监听“添加超大群成员的通知”,原型:onAddSuperTeamMembers(data: NIMOnAddSuperTeamMembersResult): void
onDismissSuperTeam function - 在线或多端同步时,超大群解散的回调函数,通过该回调函数监听“超大群解散的通知”,原型:onDismissSuperTeam(data: { teamId: string }): void
onRemoveSuperTeamMembers function - 在线或多端同步时,删除超大群成员的回调函数,通过该回调函数接收删除超大群成员的通知,原型:onRemoveSuperTeamMembers(data: NIMOnRemoveSuperTeamMembersResult): void您需要判定dataaccount 是否包含当前的 IM 账号, 来处理当前 IM 账号被踢出群的情况
onTransferSuperTeam function - 在线或多端同步时,转让超大群的回调函数,通过该回调函数获取超大群转让的通知,原型:onTransferSuperTeam(data: NIMOnTransferSuperTeamResult): void
onUpdateSuperTeam function - 更新超大群的回调函数,用于在用户在线或多端同步时接收更新超大群信息的通知。原型:onUpdateSuperTeam(data: Pick<NIMSuperTeam, "custom" | "announcement" | "avatar" | "intro" | "name" | "teamId" | "updateTime">): void
onUpdateSuperTeamManagers function - 更新超大群管理员的回调函数,用于在用户在线或多端同步时接收更新超大群管理员的通知。原型:onUpdateSuperTeamManagers(data: NIMOnUpdateSuperTeamManagersResult): void
onUpdateSuperTeamMembersMute function - 超大群成员被禁言的回调函数,用户可在在线或多端同步时接收超大群成员被禁言的通知。原型:onUpdateSuperTeamMembersMute(data: NIMOnUpdateSuperTeamMembersMuteResult): void
onMySuperTeamMembers function - 获取自己在所有超大群中的用户信息的回调函数。

用户资料初始化参数

参数
类型
是否必传 说明
onusers function - 回调函数,用于初始化同步时获取好友的用户名片。原型:onusers(datas: NIMUserNameCard[]): void
onblacklist function - 初始化同步时,用于获取黑名单列表的回调函数。原型:onblacklist(datas: NIMMarkedUserInfo[]): void
onmyinfo function - 初始化同步时,用于用户获得自己的用户名称。原型:onmyinfo(data: NIMUserNameCard): void
onupdatemyinfo function - 用于在多端同步时获取当前用户自己的用户名片更新的回调函数。原型:onupdatemyinfo(data: NIMUserNameCard): void
onupdateuser function - 用于在线接收消息后,获取聊天对象的用户名片信息更新的回调函数。原型:onupdateuser(data: NIMUserNameCard): void

用户关系初始化参数

参数
类型
是否必传 说明
onfriends function - 同步好友列表的回调, 会传入好友列表。原型:onfriends(datas: NIMFriendProfile[]): void
onmutelist function - 用于在初始化同步时接收静音用户列表的回调函数。原型:onmutelist(datas: NIMMarkedUserInfo[]): void
onsyncfriendaction function - 用于在多端同步时获取好友动作(如添加好友、好友申请、拒绝好友申请等)的回调函数。原型:onsyncfriendaction(data: NIMOnSyncFriendActionResult): void
onsyncmarkinblacklist function - 用于在多端同步时接收拉黑/移出黑名单事件的回调函数。原型:onsyncmarkinblacklist(data: NIMMarkedUserResult): void
onsyncmarkinmutelist function - 用于在多端同步时接收“静音某个用户”事件的回调函数。原型:onsyncmarkinmutelist(data: NIMMarkedUserResult): void
此文档是否对你有帮助?
有帮助
去反馈
  • 功能介绍
  • 使用限制
  • 前提条件
  • 实现流程
  • 步骤1:准备 Token
  • 获取静态 Token
  • 获取动态 Token
  • 步骤2:初始化并登录
  • 登录方式概览
  • 静态 token 登录
  • 动态 Token 登录
  • 通过第三方回调登录
  • 相关信息
  • 示例代码
  • 更新 IM 初始化配置
  • 出海配置
  • 多端登录与互踢
  • 初始化参数