IM 即时通讯
Web
产品介绍
简介
主要功能
产品优势
海外数据中心
IM平滑迁移方案
接口及业务限制
功能介绍
帐号集成与登录
基础消息功能
群组功能
聊天室功能
聊天室标签功能
多端登录与互踢策略
质量数据监控台
体验 Demo
下载 SDK 与 Demo 源码
更新日志
IM UIKit 更新日志
NIM SDK 开发版更新日志
NIM SDK 稳定版更新日志
快速开始
跑通 IM Demo 源码
实现 IM 文本消息收发(不含 UI)
含 UI 集成
什么是 IM UIKit
IM UIKit 功能概览
快速集成 IM UIKit
非React框架集成 IM UIKit
组件导入
初始化
全局上下文
登录相关
实现消息收发及界面自定义
集成会话列表界面
集成会话消息界面
集成用户资料组件
集成通讯录界面
集成搜索组件
主题样式设置
语言设置
初始化(兼容 NIM SDK)
不含 UI 集成
集成 SDK
初始化与登录
登录登出
消息相关
消息概述
消息收发
消息配置选项
广播消息收发
消息已读回执
消息撤回
消息重发与转发
本地消息
通知消息
群通知消息
超大群通知消息
历史消息
最近会话
用户资料托管
好友关系托管
用户关系托管
在线状态订阅
群组功能
群组概述
群组管理
群成员管理
群消息管理
超大群功能
系统通知
系统通知概述
内置系统通知管理
内置系统通知未读数
自定义系统通知收发
开通聊天室功能
聊天室
反垃圾
域名高可用
融合存储方案
扩展功能
工具方法
最佳实践
聊天室重要消息投递
API参考
SDK API (Web)
IM UIKit Store API
状态码
IM 控制台指南
创建应用
注册 IM 账号
升级服务
开通聊天室功能
配置应用客户端标识
常见问题
FAQ
服务协议

集成 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_*.jsNIM_Web_Chatroom_*.jsNIM_Web_SDK_*.jsNIM_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>
  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),两种方式都只在主线程触发。

  • 一般回调接口直接反映在对应接口的 done 参数上,调用时设置即可。
  • 委托则需要开发者在合适时机在初始化异步监听函数上进行处理
  // 委托通知示例
  var nim = NIM.getInstance({
    // ... 此处省略其他配置
    onmsg: function (msg) {
      // 此处为委托消息事件,消息发送成功后,成功消息也在此处处理
    }
  });


  // 回调通知示例
  var msg = nim.sendText({
    scene: 'p2p',
    to: account,
    text: 'hello',
    done: function sendMsgDone (error, msg) {
      // 此处为回调消息事件,仅仅通知开发者,消息是否发送成功
    }
  });
此文档是否对你有帮助?
有帮助
我要吐槽
  • SDK 安装
  • SDK 选择
  • 浏览器环境集成
  • 跨平台环境集成
  • 小程序
  • 小程序概述
  • WebSocket连接数量
  • 域名白名单
  • Nodejs
  • Nodejs概述
  • 本地数据库
  • 文件发送
  • 日志记录
  • SDK引入方式
  • script引入
  • import/require引入
  • 使用说明
  • 实例调用方式
  • 事件通知方式