集成方式

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

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

Web-SDK 跨平台环境支持微信/字节跳动小程序、React Native、Nodejs等场景应用。

SDK选择

如果只使用 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 和聊天室的实例。

浏览器环境集成

请前往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开始支持。
字节跳动小程序：从v7.8.0开始支持。

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

WebSocket连接数量

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

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

域名白名单

React Native

React Native概述

v5.3.0开始，云信 Web-SDK 对 React Native 做了适配，推荐 RN版本 >=0.51。云信WebSDK React Native(以下简称RN-SDK)的大部分API使用方法与SDK在Web浏览器环境使用相同，以减少开发者使用SDK所带来的障碍。

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

本地数据库

RN-SDK支持含数据库和不含数据库的使用方式，根据开发者的业务场景，可自行处理。

不使用数据库，即在IM初始化时对db设为false即可，如：

  const nim = NIM.getInstance({
    debug: true,
    appKey: appKey,
    account: account,
    token: token,
    db: false,  // 不使用数据库
    onconnect: onConnect,
    onwillreconnect: onWillReconnect,
    ondisconnect: onDisconnect,
    onerror: onError
  });

使用数据库，需要开发者安装使用realm，RN-SDK目前自身不支持但不限制使用sqlite3作为本地数据库。可以通过usePlugin方法将数据库挂在到SDK实例上，用法如下：

  const SDK = require('NIM_Web_SDK_vx.x.x.js');
  const Realm = require('realm');
  // 此处将外置的realm数据库挂载到sdk上，供sdk使用
  SDK.usePlugin({
    db: Realm,
  });
  const nim = SDK.NIM.getInstance({
    debug: true,
    appKey: appKey,
    account: account,
    token: token,
    db: true,   // 使用数据库
    onconnect: onConnect,
    onwillreconnect: onWillReconnect,
    ondisconnect: onDisconnect,
    onerror: onError
  });

本地日志

RN-SDK支持本地日志存储及远程拉取，开发者可以根据需求选择是否使用本地日志功能。

使用本地日志功能后，SDK会将日志以文件的形式写到用户的终端（手机）上，用户在线时，可以调用服务端接口拉取用户终端上的日志，便于排查问题。

本地存储依赖react-native-fs库，具体使用方法如下：

安装react-native-fs
```
npm install react-native-fs --save
```

通过usePlugin方法将数据库挂在到sdk上，如下

const RNFS = require('react-native-fs');

const params = {
 rnfs: RNFS
};
params.rnfs.size = 1024 * 1024;  // 日志文件体积上限，单位:bytes; 选填，默认为1M
SDK.usePlugin(params);

const nim = SDK.NIM.getInstance({
 // .....
 // 初始化IM
});

消息推送

v5.3.0版本开始支持推送能力，开发者在配置工程时，需要引入相应的安卓和APNs推送依赖。

APNs推送
- APNs推送配置首先需要开发者去苹果官网申请具有推送能力的证书；
- 配置完证书后，按照 RN 推送配置添加相关能力。
安卓推送
- 参考 RN-Demo 的 ./android/nimpush与./nim/NIM_Android_Push.js；
- 配置参见安卓推送配置。

若不需要推送，则初始化时相关的iosPushConfig与androidPushConfig参数不填即可。

示例代码：

  // iOS/安卓端外推送代码
  const iosPushConfig = {
    tokenName: 'push_online',
  };
  const androidPushConfig = {
    xmAppId: '2882303106219',
    xmAppKey: '59717219',
    xmCertificateName: 'RN_MI_PUSH',
    hwCertificateName: 'RN_HW_PUSH',
    mzAppId: '11398',
    mzAppKey: 'b74148973e60a2af4c2f6779',
    mzCertificateName: 'RN_MZ_PUSH',
    fcmCertificateName: 'RN_FCM_PUSH',
    vivoCertificateName: "vivopush",
    oppoAppId: "xxx", // oppoAppId，oppoAppKey，oppoAppSercet 在oppo推送平台注册得到
    oppoAppKey: "xxx",
    oppoAppSercet: "xxx",
    oppoCertificateName: "oppopush"
  };
  var nim = SDK.NIM.getInstance({
    // ...
    iosPushConfig,
    androidPushConfig,
    // ...
  })

  // 安卓端内推送示例代码，非远程推送
  import { showNotification } from '../nim/NIM_Android_Push';
  showNotification({
    icon: '', title: msg.from, content: showText, time: `${msg.time}`,
  });

文件发送

由于RN-SDK发送文件消息需要额外获取文件消息的属性一起发送，所以不建议直接使用sendFile接口发送文件，而是先通过previewFile获取文件的句柄，通过其他api方法将文件属性添加回文件对象，最后再使用sendFile接口发送文件。以下为发送图片文件的示例：

  nim.previewFile({
    type: 'image',
    filePath: options.filePath,
    maxSize: maxSize,
    commonUpload: true,
    uploadprogress(obj) {
      // ...
    },
    done: (error, file) => {
      // 通过其他API接口获取到长、宽、大小等图片属性
      file.w = options.width;
      file.h = options.height;
      file.md5 = options.md5;
      file.size = options.size;
      const { scene, to } = options;
      if (!error) {
        constObj.nim.sendFile({
          type: 'image',
          scene,
          to,
          file,
          done: (err, msg) => {
            if (err) {
              return;
            }
            this.appendMsg(msg);
          },
        });
      }
    },
  });

消息需要额外附加属性列表：
- 图片对象
  - size: 大小，单位byte
  - md5: 图片文件的md5转换后的值
  - w: 宽，单位px
  - h: 高，单位px
- 音频对象
  - size: 大小，单位byte
  - md5: 音频文件的md5转换后的值
  - dur: 长度，单位ms
- 视频对象
  - size: 大小，单位byte
  - md5: 视频文件的md5转换后的值
  - w: 宽，单位px
  - h: 高，单位px
  - dur: 长度，单位ms
- 文件对象
  - size: 大小，单位byte
  - md5: 文件的md5转换后的值

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)，两种方式都只在主线程触发(为保证浏览器兼容性，没有使用web worker)。

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

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


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

本篇文档内容是否对您有帮助？

有帮助

我要吐槽

您的改进建议

问题类型

内容错误内容没更新描述不清链接有误步骤不完整内容缺失（缺少代码/示例）其他

更多建议

请输入您的建议或问题（至少5个字符，至多500个字符）

联系方式

标记内容

同时提交标记内容

此文档对你是否有帮助

有帮助

我要吐槽

反馈成功

非常感谢您的反馈，我们会继续努力做得更好。

IM即时通讯

产品介绍

服务端API文档

SDK开发集成

iOS开发集成

Android开发集成

Windows开发集成

Linux开发集成

Web开发集成

Unity开发集成

Cocos2d-x开发集成

更新日志

Demo更新日志

集成方式

SDK选择

浏览器环境集成

跨平台环境集成

小程序

小程序概述

WebSocket连接数量

域名白名单

React Native

React Native概述

本地数据库

本地日志

消息推送

文件发送

Nodejs

Nodejs概述

本地数据库

文件发送

日志记录

SDK引入方式

script引入

import/require引入

使用说明

实例调用方式

事件通知方式

相关文档

相关产品

您的改进建议

此文档对你是否有帮助

反馈成功