集成 SDK
更新时间: 2023/02/02 10:04:32
网易云信 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>
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) {
// 此处为回调消息事件,仅仅通知开发者,消息是否发送成功
}
});