开发者中心
IM 即时通讯
IM 即时通讯
全部产品
中文
Web
新手接入指南
产品介绍
简介
主要功能
接口及业务限制
功能介绍
帐号集成与登录
基础消息功能
群组功能
聊天室功能
聊天室标签功能
消息抄送服务
第三方回调功能
多端登录与互踢策略
质量数据监控台
更新日志
更新日志
Demo 更新日志
开发集成
集成方式
初始化
登录登出
消息收发
最近会话
用户资料托管
好友关系托管
用户关系托管
在线状态订阅
历史消息
系统通知
群组功能
超大群功能
聊天室
客户端反垃圾
域名高可用
扩展功能
工具方法
API参考
Web API 参考
状态码
参考文档
Demo源码导读
Web H5 源码导读
IM平滑迁移方案
UI库指南-Web
常见问题

集成方式

更新时间: 2021/08/02 17:29:08

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

Web-SDK 浏览器环境兼容IE9+、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回调以后再去发起新的连接。

域名白名单

相关配置列表如下:

  • request 合法域名:

    • https://lbs.netease.im
    • https://wlnimsc0.netease.im ( IM必需 )
    • https://wlnimsc1.netease.im ( 聊天室必需 )
  • socket 合法域名:

    • wss://wlnimsc0.netease.im ( IM必需 )
    • wss://wlnimsc1.netease.im ( 聊天室必需 )
  • uploadFile 合法域名:

    • https://nos.netease.com ( 云信文件上传必需,如发送文件类消息等 )
  • downloadFile合法域名:

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

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库,具体使用方法如下:

  1. 安装react-native-fs
npm install react-native-fs --save
  1. 通过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
    • 配置参见安卓推送配置

若不需要推送,则初始化时相关的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);
          },
        });
      }
    },
  });
  • 消息需要额外附加属性列表:
    • 图片对象
      • 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) {
      // 此处为回调消息事件,仅仅通知开发者,消息是否发送成功
    }
  });
此文档是否对你有帮助?
有帮助
我要吐槽
文档反馈
  • SDK选择
  • 浏览器环境集成
  • 跨平台环境集成
  • 小程序
  • 小程序概述
  • WebSocket连接数量
  • 域名白名单
  • React Native
  • React Native概述
  • 本地数据库
  • 本地日志
  • 消息推送
  • 文件发送
  • Nodejs
  • Nodejs概述
  • 本地数据库
  • 文件发送
  • 日志记录
  • SDK引入方式
  • script引入
  • import/require引入
  • 使用说明
  • 实例调用方式
  • 事件通知方式