集成JS代码
NIM SDK 需要您通过手动下载 SDK, 然后添加到您的项目中。
下载SDK
请至官网SDK 下载入口下载。
SDK 目录结构介绍
- 如果要在浏览器里面使用 SDK, 相应的 JS 文件都在
js目录下. - 如果要在跨平台环境中使用 SDK，JS符号umd规范，可以通过
require的方式引入
- 如果要在浏览器里面使用 SDK, 相应的 JS 文件都在
引入SDK
SDK选择
如果要使用 IM 功能, 请引入
NIM_Web_NIM_v.js- 请通过
NIM来获取引用
- 请通过
如果要使用聊天室功能, 请引入
NIM_Web_Chatroom_v.js- 请通过
Chatroom来获取引用
- 请通过
如果同时使用 IM 和聊天室功能, 请引入
NIM_Web_SDK_v.js如果通过 script 标签引入, 请通过
SDK.NIM和SDK.Chatroom来获取NIM和Chatroom的引用, 下文中的 API 都是通过NIM和Chatroom来调用的
如果要使用插件版实时音视频功能, 请引入
NIM_Web_Netcall_v.js, 通过Netcall来获取引用, 调用NIM.use(Netcall)来加载实时音视频插件如果要使用WebRTC实时音视频功能, 请引入
NIM_Web_WebRTC_v.js, 通过WebRTC来获取引用, 调用NIM.use(WebRTC)来加载实时音视频插件如果要使用教学白板/数据通道功能, 请引入
NIM_Web_WhiteBoard_v.js, 通过WhiteBoard来获取引用, 调用NIM.use(WhiteBoard)来加载实时白板插件
SDK引入方式
- script 标签方式引用(浏览器中)
- 将所需的SDK脚本，通过传入script标签的src中
- 在下文中使用window对象属性即可获取对sdk的引用
<!-- 例如 -->
<script src="NIM_Web_SDK.js"></script>- import/require 方式引用(浏览器框架及跨平台环境中)
- 直接使用import/require方式获取引用
- 如果开发者选用 webpack/babel 来打包, 那么请使用 exclude 将 SDK 文件排除, 避免 babel 二次打包引起的错误
SDK在工程中调用示例：
// 使用示例
import SDK from 'NIM_Web_SDK.js'
const nim = SDK.NIM.getInstance({
// ...
})相对应Webpack配置
// Webpack 参考配置
module: {
rules: [
{
test: /\.js$/,
loader: 'babel-loader',
exclude: /NIM_Web_SDK.*\.js/,
query: {
presets: [
// ...
],
// ...
}
// ...
},
// ...
],
// ...
}使用说明
实例调用方式
所有业务均通过 NIM SDK 单例调用
// 引入SDK类的引用以后，获取SDK对象实例
var nim = SDK.NIM.getInstance({
// debug: true,
appKey: 'appKey',
account: 'account',
token: 'token',
// privateConf: {}, // 私有化部署方案所需的配置
// ...
})以发送点对点消息为例：
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) {
// 此处为回调消息事件，仅仅通知开发者，消息是否发送成功
}
})
浏览器兼容性
云信 Web SDK (不包含实时音视频)兼容到 IE9+ (5.0.0以下版本支持IE8)
- IE8/IE9 需要将项目部署在 HTTPS 环境下才能连接到云信服务器, 其它高级浏览器可以在 HTTP 或者 HTTPS 环境下连接到云信服务器
数据库兼容性
- 浏览器环境
- 在支持数据库的浏览器上 SDK 会将数据缓存到数据库中, 后续同步都是增量更新, 加快初始化速度。
- Web SDK在底层使用了indexedDb，作为数据库进行存储。由于浏览器兼容性及其本身设计上的限制/缺陷（如读写库性能问题、数据空间、没有数据库表级别锁、不能只修改对象单个字段、非阻塞等等问题），用户场景没有强烈需要本地数据存储的应用，不建议开启数据库。
ReactNative环境
- 用户可以不使用数据库，SDK支持Realm作为数据库
小程序、Nodejs环境
- 不支持数据库，nodejs用户可在上层做封装。
是否支持数据库
// 通过此 `boolean` 值来查看 SDK 在某个浏览器上是否支持数据库
NIM.support.db其原理是结合了JavaScript"鸭子类型"探测和UserAgent识别，做判断，所以非法改写的UserAgent可能会导致报错。
不使用数据库
如果开发者不想使用数据库, 那么可以设置初始化参数db为false来禁用数据库。云信Sdk默认为开启。
var nim = NIM.getInstance({
db: false
});