集成方式
网易云信 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
回调以后再去发起新的连接。
域名白名单
相关配置列表如下:
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库,具体使用方法如下:
安装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
; - 配置参见安卓推送配置。
- 参考 RN-Demo 的
若不需要推送,则初始化时相关的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>
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) {
// 此处为回调消息事件,仅仅通知开发者,消息是否发送成功
}
});


此文档对你是否有帮助

