集成JS代码
NIM SDK 需要您通过手动下载 SDK, 然后添加到您的项目中。
下载SDK
我们提供两个SDK获取方式。分别为:
- 官网 SDK 下载入口。
- 向客户经理咨询并索要尝鲜版Web功能
- 从我们提供的
github
demo中获取相关js文件
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
来禁用数据库
var nim = NIM.getInstance({
db: false
});