文档反馈
文档反馈

集成方式

网易云信 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选择

浏览器环境集成

请前往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。

由于浏览器环境的全局变量为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支持含数据库和不含数据库的使用方式,根据开发者的业务场景,可自行处理。

  const nim = NIM.getInstance({
    debug: true,
    appKey: appKey,
    account: account,
    token: token,
    db: false,  // 不使用数据库
    onconnect: onConnect,
    onwillreconnect: onWillReconnect,
    ondisconnect: onDisconnect,
    onerror: onError
  });
  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库,具体使用方法如下:

  1. 安装react-native-fs

    npm install react-native-fs --save
  2. 通过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推送依赖。

若不需要推送,则初始化时相关的iosPushConfigandroidPushConfig参数不填即可。

示例代码:

  // 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);
          },
        });
      }
    },
  });

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的日志记录。

  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');
  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)。

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


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

反馈成功

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