网易云信 JavaScript SDK(Web-SDK) 为PC/移动Web应用及NodeJS、微信小程序等跨平台应用，提供完善的即时通信功能开发能力，屏蔽其内部复杂细节，对外提供较为简洁的 API 接口，方便第三方应用快速集成即时通信功能。

Web-SDK 浏览器环境兼容IE9+、Edge、Chrome 58+、 Safari 10+、Firefox 54+等主流桌面版浏览器，兼容iPhone 5s以上机型(操作系统iOS 8.0+)的Safari浏览器及其内置微信浏览器、主流机型Android 5+系统的Chrome浏览器及其内置微信浏览器。

SDK 安装

• 通过 npm 命令进行安装。

  npm install @yxim/nim-web-sdk@latest
  

• 在云信官网下载 SDK 后引入 IM 功能模块。

import SDK from 'NIM_Web_NIM_vx.x.x.js'

x.x.x 是对应 SDK 版本号，请查看SDK 更新日志使用最新版本。

SDK 选择

SDK 默认提供以下几种形式：

dist/SDK
├── NIM_Web_Chatroom_miniapp.js  聊天室小程序适配版 UMD 格式
├── NIM_Web_Chatroom_nodejs.js  聊天室node适配版 UMD 格式
├── NIM_Web_Chatroom_rn.js   聊天室 React-Native 适配版 UMD 格式
├── NIM_Web_Chatroom.js       聊天室浏览器适配版 UMD 格式
├── NIM_Web_NIM_miniapp.js  IM 小程序适配版 UMD 格式
├── NIM_Web_NIM_nodejs.js  IM node 适配版 UMD 格式
├── NIM_Web_NIM_rn.js   IM React-Native 适配版 UMD 格式
├── NIM_Web_NIM.js       IM 浏览器适配版 UMD 格式
├── NIM_Web_SDK_miniapp.js  集成包小程序适配版 UMD 格式
├── NIM_Web_SDK_nodejs.js  集成包node适配版 UMD 格式
├── NIM_Web_SDK_rn.js   集成包 React-Native 适配版 UMD 格式
├── NIM_Web_SDK.js       集成包浏览器适配版 UMD 格式

• 如果只使用 IM 功能，请引入 NIM_Web_NIM_*.js，并通过 NIM.getInstance({...}) 来初始化 IM 实例。

• 如果只使用 聊天室 功能，请引入NIM_Web_Chatroom_*.js，并通过 Chatroom.getInstance({...}) 来初始化聊天室实例。

• 如果同时使用 IM 和 聊天室 功能，请引入 NIM_Web_SDK_*.js，并请通过 SDK.NIM.getInstance({...}) 和 SDK.Chatroom.getInstance({...}) 来分别初始化 IM 和 聊天室的实例。

• 注意！不能同时引入 NIM_Web_SDK_*.js 和 NIM_Web_Chatroom_*.js 或 NIM_Web_SDK_*.js 和 NIM_Web_NIM_*.js 文件

浏览器环境集成

请前往SDK下载页面获取当前最新版本的浏览器环境的 Web-SDK。

注：云信 Web IM SDK 兼容到 IE9+ (5.0.0以下版本支持IE8)。IE8/IE9 需要将项目部署在 HTTPS 环境下才能连接到云信服务器，其它高级浏览器可以在 HTTP 或者 HTTPS 环境下连接到云信IM服务器。

跨平台环境集成

网易云信 Web-SDK 所提供的跨平台相关能力的接口使用方式，基本与浏览器环境下的 JavaScript 调用方式相同，用户无需付出更多学习的成本。当然，根据不同平台所特有的一些差异点，SDK 也做了一些适配，主要分布在诸如数据库使用、文件上传、WebSocket限制等方面。

小程序

小程序概述

请前往SDK下载页面获取当前最新版本的小程序的 Web-SDK。

微信小程序：从v5.1.0开始支持。

由于浏览器环境的全局变量为window，而小程序的全局变量为wx，其属性不尽相同，为了做到兼容及适配，SDK会mock一些属性，诸如navigator，location，io等，一般不影响用户正常使用。

WebSocket连接数量

微信小程序 1.7.0 及以上版本，最多可以同时存在 5 个 WebSocket 连接,同域名的WebSocket 连接最多两条。所以在使用多条socket的时候，务必要控制好连接数量。

用户切换账号、聊天室使用新的实例时，为保证不超过小程序WS连接限制，务必先执行IM/聊天室实例的destroy方法，并在done回调以后再去发起新的连接。

域名白名单

相关配置列表如下：

• request 合法域名：

  • https://lbs.netease.im
  • https://wlnimsc0.netease.im （IM 必需）
  • https://wlnimsc1.netease.im （聊天室必需）
  • https://wlnimsc0.netease.im:443 （IM 必需）
  • https://wlnimsc1.netease.im:443 （聊天室必需）
  • https://statistic.live.126.net （数据上报必需）
  • https://abt-online.netease.im （用于 abtest）

• socket 合法域名:

  • wss://wlnimsc0.netease.im （ IM必需 ）
  • wss://wlnimsc1.netease.im （ 聊天室必需 ）

• uploadFile 合法域名:

  • https://nos.netease.com ( 云信文件上传必需，如发送文件类消息等 )

• downloadFile合法域名:

  • https://nim-nosdn.netease.im ( 云信资源文件下载必需，如下载语音等 )

Nodejs

Nodejs概述

v5.6.0开始，云信WebSDK官方对node js做了适配，可以将即时通讯应用业务场景推广到拥有Nodejs环境的服务端。使用nodejs解决方案，可以充分运用到服务器即客户端，客户端即服务器的使用场景中，诸如linux工业控制、聊天机器人、数据管道、单机监控、规模化数据分析等等。

由于浏览器环境的全局变量为window，而nodejs的全局变量为global，其属性不尽相同，为了做到兼容及适配，SDK会mock一些属性，诸如navigator，location，WebSocket等对象到global中，一般不影响用户正常使用。

请联系云信技术支持获取对应的SDK文件。

本地数据库

由于服务器环境的存储系统具有多样性，SDK不在内部再对数据库进行集成，用户可以自行使用诸如mysql、oracle、ms-sql、sqlite、mongodb、hbase等等数据存储服务。 使用nodejs sdk的同时，用户依然可以使用网易云信的server-api所提供的能力，直接对服务器数据进行操作，事半功倍。

文件发送

Nodejs的上传接口请使用filePath参数：

  nim.previewFile({
    type: 'image',
    maxSize: maxSize,
    commonUpload: true,
    filePath: options.filePath,
    uploadprogress(obj) {
      // ...
    },
    done: (error, file) => {
      const { scene, to } = options;
      if (!error) {
        constObj.nim.sendFile({
          type: 'image',
          scene,
          to,
          file,
          done: (err, msg) => {
            if (err) {
              return;
            }
            this.appendMsg(msg);
          },
        });
      }
    },
  });

日志记录

SDK支持使用第三方的日志记录工具，辅助客户在服务器端使用文件log的方式记录日志，以下以npm-log4js 3.*第三方库为例，进行SDK的日志记录。

• 初始化log4js:

  const log4js = require('log4js');
  log4js.configure({
    replaceConsole: true,
    appenders: { nimlog: { type: 'file', filename: 'nim-debug.log' } },
    categories: { default: { appenders: ['nimlog'], level: 'ALL' } }
  });
  const logger = log4js.getLogger('nimlog');

• IM及聊天室部分日志插件引入方式：

  global.nim = NIM.getInstance({
    debug: true,
    logFunc: logger,
    // ...
  })

SDK引入方式

script引入

将所需的SDK文件，传入script标签的src中即可。在下文中使用window对象属性即可获取对SDK的引用。

<!-- 例如 -->
<script src="NIM_Web_SDK_vx.x.x.js">
<script>
  var nim = SDK.NIM.getInstance({
    // ...
  })
</script>

import/require引入

在浏览器框架及跨平台环境中，可以使用import/require 方式引用SDK。

注意：如果开发者选用 webpack/babel 来打包，那么请使用 exclude 将 SDK 文件排除，避免 babel 二次打包引起的错误。

SDK在工程中调用示例：

  // 使用示例
  import SDK from 'NIM_Web_SDK_vx.x.x.js'
  const nim = SDK.NIM.getInstance({
    // ...
  })

相对应Webpack配置：

  // Webpack 参考配置
  module: {
    rules: [
      {
        test: /\.js$/,
        loader: 'babel-loader',
        exclude: /NIM_Web_SDK_vx.x.x.js/,
        query: {
          presets: [
            // ...
          ],
          // ...
        }
        // ...
      },
      // ...
    ],
    // ...
  }

使用说明

实例调用方式

所有业务均通过 NIM SDK 单例调用，例如：

  // 引入SDK类的引用以后，获取SDK对象实例
  var nim = SDK.NIM.getInstance({
    debug: true,
    appKey: appKey,
    account: account,
    token: token,
    // ...
  });

以发送点对点消息为例：

  var msg = nim.sendText({
    scene: 'p2p',
    to: account,
    text: 'hello',
    done: function sendMsgDone (error, msg) {
      // ...
    }
  });

事件通知方式

SDK 通过两种方式通知上层 API 调用结果：回调(callback)和委托 (delegate)，两种方式都只在主线程触发。

• 一般回调接口直接反映在对应接口的 done 参数上，调用时设置即可。
• 委托则需要开发者在合适时机在初始化异步监听函数上进行处理

  // 委托通知示例
  var nim = NIM.getInstance({
    // ... 此处省略其他配置
    onmsg: function (msg) {
      // 此处为委托消息事件，消息发送成功后，成功消息也在此处处理
    }
  });


  // 回调通知示例
  var msg = nim.sendText({
    scene: 'p2p',
    to: account,
    text: 'hello',
    done: function sendMsgDone (error, msg) {
      // 此处为回调消息事件，仅仅通知开发者，消息是否发送成功
    }
  });