IM 即时通讯(增强版)
Web
新手接入指南
产品介绍
简介
产品优势
主要功能
功能介绍
账号集成与登录
基础消息功能
群组功能
聊天室功能
圈组功能
多端登录与互踢策略
海外数据中心
IM 平滑迁移方案
接口及业务限制
更新日志
IM UIKit 更新日志
NIM SDK 更新日志
体验 Demo
下载 SDK 与 Demo 源码
快速开始
跑通 IM Demo 源码
实现单聊消息收发(不含 UI)
实现圈组消息收发(不含 UI)
含 UI 集成
什么是 IM UIKit
IM UIKit 功能列表
快速集成 IM UIKit
非React框架集成 IM UIKit
组件导入
初始化
全局上下文
登录相关
实现消息收发及界面自定义
集成会话列表界面
集成会话消息界面
集成用户资料组件
集成通讯录界面
集成搜索组件
非 React 框架自定义示渲染
主题样式设置
语言设置
初始化(兼容 NIM SDK)
不含 UI 集成
SDK 集成概述
小程序环境集成声明
初始化与登录
消息收发
历史消息
消息扩展
最近会话
用户资料托管
好友关系托管
在线状态订阅
系统通知
群组功能
群组概述
群组管理
群成员管理
群消息管理
超大群功能
超大群概述
超大群管理
超大群成员管理
超大群消息管理
反垃圾
聊天室功能
聊天室概述
聊天室标签功能
快速实现聊天室登录
聊天室消息管理
聊天室成员管理
聊天室信息管理
聊天室队列服务
圈组功能
圈组概述
初始化与登录
通用接口校验说明
服务器相关
服务器概述
服务器管理
服务器成员管理
游客功能
服务器未读数管理
频道相关
频道概述
频道管理
频道黑白名单
频道分组
频道分组黑白名单
频道未读数管理
实时互动频道
搜索服务器与频道
身份组相关
身份组概述
身份组应用场景
服务器身份组
频道身份组
频道用户定制权限
频道分组身份组
自定义权限项
成员权限查询与判定
身份组相关查询
圈组订阅机制
圈组消息相关
圈组消息收发
圈组消息撤回
圈组消息更新
圈组消息删除
消息正在输入
获取频道最后一条消息
会话消息回复(Thread)
圈组快捷评论
圈组消息搜索
查询历史消息
查询@我的消息
圈组系统通知相关
圈组系统通知概述
圈组系统通知收发
圈组系统通知更新
圈组内容审核
圈组第三方回调
圈组相关抄送
圈组各端接口命名差异
融合存储方案
uniapp 推送相关
最佳实践
聊天室重要消息投递
API 参考
NIM SDK API 参考
状态码
IM 控制台指南
创建应用
注册 IM 账号
升级服务
服务协议

小程序环境集成声明

更新时间: 2023/02/02 10:57:07

NIM Web 增强版 SDK 目前兼容 uniapp 和各种小程序(微信/支付宝)环境。但这些平台对 SDK 的使用存在一些限制。本文只要介绍小程序环境集成的注意事项,并针对限制以及并列举其中的一些重要限制以及针对限制的处理办法。

SDK 所提供的小程序相关能力的接口使用方式,基本与浏览器环境下调用方式相同。但根据小程序与浏览器的差异,SDK 也做了适配,主要调用方式的差异体现在诸如文件上传、WebSocket 和网络请求限制等方面。

域名白名单配置

开始小程序环境集成前,请确保已在微信开放平台完成域名白名单配置。

相关配置列表如下:

  • 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)
  • WebSocket 合法域名:
    • wss://wlnimsc0.netease.im (IM 必需)
    • wss://wlnimsc1.netease.im (聊天室必需)
  • uploadFile 合法域名:
    • https://nos.netease.com (云信文件上传必需,如发送文件类消息等)
  • downloadFile合法域名:
    • https://nim-nosdn.netease.im (云信资源文件下载必需,如下载图片、文件等)

WebSocket 连接限制

  • 微信小程序 1.7.0 及以上版本,最多可同时存在 5 条 WebSocket 连接,其中同域名的 WebSocket 连接最多 2 条。 如需在切换账号或聊天室时使用新实例,为保证不超过小程序 WebSocket 连接限制,请务必先调用 IM /聊天室实例的 destroy 方法,并在 promise 完成后以后再去创建新的实例。
  • uniapp 项目在真机上运行(作为 app 运行,而非 H5),websocket只能连接一个 websocket。 自定义组件模式下是基于 weex 的 v8 引擎运行,所有 vue 页面的 js 都是在同一个 weex 的 js 环境中运行。目前 weex 限制一个 js 环境中只支持一个 websocket 连接,所以导致所有 vue 页面只能使用一个 websocket 连接。 IM 和 Chatroom 是分两个实例各自独立建立两个长连接的。所以编译成 uniapp app 的模式下,请不要同时使用两个实例。

初始化的配置

实例在小程序环境中运行,会受到下文的域名白名单限制,无法使用动态的基于位置的服务 (LBS) 自动调配长连接地址,所以初始化过程中的 LBS 只能使用一个固定的地址。

如下为使用固定 LBS 地址的示例:

import NIMSDK from 'nim-web-sdk-ng/dist/NIM_MINIAPP_SDK

const nim = new NIMSDK({
  appkey: "YOUR_APPKEY",
  token: "YOUR_TOKEN",
  account: "YOUR_ACCOUNT",
  lbsUrls: [
    "https://lbs.netease.im/lbs/wxwebconf.jsp"
  ],
  linkUrl: "wlnimsc0.netease.im"
})

uniapp 运行在小程序环境中也需进行上述初始化配置。

不支持分片上传

uniapp、小程序环境不支持分片上传。

由于读取文件有着诸多限制,无法以一种兼容性比较好的方式根据 filePath 拿到本地文件信息。单线程在上传大文件不仅体验很差,还会根据手机终端表现,会出一些意想不到的问题。

建议开发者在使用选择文件 API (chooseImage,choosevideo)时自行判断文件大小,100 MB 以上的不传。

微信小程序编译问题

  • uniapp 编译成微信小程序时,会直接在微信小程序上报错 “Function(...) is not a function”。

    出现该问题的原因是微信基础库版本过低,请切换 2.21.0 以上的版本。

  • uniapp 编译成微信小程序时,会在小程序上报错 “TypeError: Converting circular structure to JSON”。

    TypeError: Converting circular structure to JSON
        --> starting at object with constructor 'i'
        |     property '_events' -> object with constructor 'n'
        |     property 'logined' -> object with constructor 'Array'
        |     index 0 -> object with constructor 'a'
        --- property 'context' closes the circle
        at JSON.stringify (<anonymous>)
        at cloneWithData (mp.runtime.esm.js?66fd:5620)
    

    出现该问题的原因是 uniapp 编译微信小程序时注入的 mp.runtime.esm.js 里,对 vue 的 data 序列化使用的序列化方法是 return JSON.parse(JSON.stringify(ret))。即在 vue 组件的 data 里挂载 nim 实例。然而实例继承自 EventEmitter3 对象,无法被这样序列化。

    建议将 nim 实例挂载在全局变量、vuex 的 prototype,或者参考如下示例代码在应用的globalData中挂载:

    const app = getApp() 
    if (app && app.globalData && app.globalData.nim) {
      app.globalData.nim = new NIMSDK()
    }
    
  • 微信小程序开启 将 JS 编译成 ES5 选项后,编译报错。

    WAServiceMainContext.js:2 TypeError: t is not a function
        at oe.connect (NIM.js? [sm]:15)
        at Li.connect (im.js? [sm]:17)
        at Object.i.safeCallback (WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2)
        at WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2
        at br (WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2)
        at WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2
        at g (WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2)
        at WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2
        at WASubContext.js?t=wechat&s=1642128708420&v=2.21.3:2
        at WAServiceMainContext.js:2(env: Windows,mp,1.05.2111300; lib: 2.21.3)
    

    建议不要开启 ES5 选项。

此文档是否对你有帮助?
有帮助
我要吐槽
  • 域名白名单配置
  • WebSocket 连接限制
  • 初始化的配置
  • 不支持分片上传
  • 微信小程序编译问题