即时通讯框架MobileIMSDK的微信小程序端开发者手册

JackJiang · 1 年前

► 相关链接：

① MobileIMSDK-微信小程序端的详细介绍
② MobileIMSDK-微信小程序端的开发手册^new（* 精编PDF版）

一、理论知识准备

您需要对微信小程序开发有所了解：

您需要对WebSocket技术有所了解：

标准WebSocket协议文档、API手册：

1）WebSocket的API手册
2）WebSocket的RFC标准文档

微信小程序中的WebSocket API手册：

1）微信官方WebSocket文档链接

小提示：微信小程序中的WebSocket API跟标准HTML5中的WebSocket接口及用法略有不同，但主要API都能一一对应，相差不大。

二、开发工具准备

1）微信小程序开发工具：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_1.png

（JackJiang使用的版本号如上图所示，为了方便直接引用工程，建议你也使用此版或较新版本）

2）一站式下载地址：微信官方下载地址点此进入。

3）微信小程序开发工具效果预览：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_2.png

三、SDK文件用途说明

3.1 文件概览

纯微信标准JS API实现，无任何第3方库依赖：

MobileIMSDK-微信小程序端SDK本身只是JS文件源码的集合，自带的Demo代码只是为了方便随时测试SDK代码，目的主要是用于演示SDK的API调用，Demo代码不属于SDK框架的一部分。

工程目录说明：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_3.png

3.2 详细说明

SDK各模块/文件作用说明：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_4.png

四、主要API接口

4.1 主要API接口概览

所有SDK接口均由 /mobileimsdk/mobileimsdk-client-sdk.js 提供。

以下是主要API接口概览图：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_5.png

如下图所示：接口设计跟MobileIMSDK的APP版一样，均为高内聚和低侵入式的回调方式传入业务层处理逻辑，无需（也不建议）开发者直接修改SDK级代码。

即时通讯框架MobileIMSDK的微信小程序端开发者手册_6.png

4.2 主要API接口用途说明

1）IMSDK.isLogined()：

用途：是否已经完成过首次登陆。
说明：用户一旦从自已的应用中完成登陆IM服务器后，本方法就会一直返回true（直到退出登陆IM）。
返回值：{boolean}，true表示已完成首次成功登陆（即已经成功登陆过IM服务端了，后面掉线时不影响此标识），否则表示尚未连接IM服务器。

2）IMSDK.isOnline()：

用途：是否在线。
说明：表示网络连接是否正常。
返回值：{boolean}，true表示网络连接正常，否则表示已掉线，本字段只在this._logined=true时有意义（如果都没有登陆到IM服务器，怎么存在在线或掉线的概念呢）。

3）IMSDK.getLoginInfo()：

用途：返回登陆时提交的登陆信息（用户名、密码/token等）。
说明：格式形如：{loginUserId:'',loginToken:''}，此返回值的内容由调用登陆函数 loginImpl()时传入的内容决定。字段定义详见：PLoginInfo。
返回值：{boolean}，true表示网络连接正常，否则表示已掉线，本字段只在this._logined=true时有意义（如果都没有登陆到IM服务器，怎么存在在线或掉线的概念呢）。

4）IMSDK.sendData(p, fnSucess, fnFail, fnComplete)：

用途：向某人发送一条消息。
参数p：{Protocal} 要发送的消息协议包对象，Protocal详情请见“/module/mb_constants.js”下的createCommonData函数说明。
参数fnSuccess ：{function} 接口调用成功的回调函数，非必填项
参数fnFail ：{function} 接口调用失败的回调函数，非必填项
参数fnComplete ：{function} 接口调用结束的回调函数（调用成功、失败都会执行），非必填项
返回值：{int} 0表示成功，否则表示错误码，错码详见“/module/mb_constants.js”下的MBErrorCode对象属性说明。

5）IMSDK.disconnectSocket()：

用途：客户端主动断开客户端socket连接。
说明：当开发者登陆IM后，需要退出登陆时，调用本函数就对了，本函数相当于登陆函数 loginImpl()的逆操作。

6）IMSDK.setDebugCoreEnable(enable)：

用途：是否开启MobileIMSDK-微信小程序端核心算法层的log输入，方便开发者调试。
参数enable：{boolean} true表示开启log输出，否则不输出，开发者不调用本函数的话系统默认是false（即不输出log）。

7）IMSDK.setDebugSDKEnable(enable)：

用途：是否开启MobileIMSDK-微信小程序端框架层的log输入，方便开发者调试。
参数enable：{boolean} true表示开启log输出，否则不输出，开发者不调用本函数的话系统默认是false（即不输出log）。

8）IMSDK.setDebugPingPongEnable(enable)：

用途：是否开启MobileIMSDK-微信小程序端框架层的底层网络WebSocket心跳包的log输出，方便开发者调试。
参数enable：{boolean} true表示开启log输出，否则不输出，开发者不调用本函数的话系统默认是false（即不输出log）。
注意：必须 setDebugEnable(true) 且 setDebugPingPongEnable(true) 时，心跳log才会真正输出，方便控制。
返回值：true表示开启log输出，否则不输出，开发者不调用本函数的话系统默认是false（即不输出log）。

9）IMSDK.loginImpl(varloginInfo, wsUrl)：

用途：登陆/连接MobileIMSDK服务器时调用的方法。
说明：登陆/连接MobileIMSDK服务器由本函数发起
参数varloginInfo：{PLoginInfo} 必填项，登陆要提交给Websocket服务器的认证信息，不可为空，对象字段定义见：PLoginInfo
参数wsUrl：{string} 必填项：要连接的Websocket服务器地址，不可为空，形如：wss://yousite.net:3000/websocket。

10）IMSDK.callback_onIMLog(message, toConsole)：

用途：由开发者设置的回调方法：用于debug的log输出。
推荐用法：开发者可在此回调中按照自已的意图打印MobileIMSDK微信小程序端框架中的log，方便调试时使用。
参数1： {String}：必填项，字符串类型，表示log内容。
参数2： {boolean}：选填项，true表示输出到console，否则默认方式(由开发者设置的回调决定)。

11）IMSDK.callback_onIMData(p, options)：

用途：由开发者设置的回调方法：用于收到聊天消息时在UI上展现出来（事件通知于收到IM消息时）。
推荐用法：开发者可在此回调中处理收到的各种IM消息。
参数1： {Protocal}：详情请见“/module/mb_constants.js”下的Protocal类定义)。

12）IMSDK.callback_onIMAfterLoginSucess()：

用途：由开发者设置的回调方法：客户端的登陆请求被服务端成功认证完成后的回调（事件通知于登陆/认证成功后）。
推荐用法：开发者可在此回调中进行登陆IM服务器成功后的处理。

13）IMSDK.callback_onIMAfterLoginFailed(isReconnect)：

用途：由开发者设置的回调方法：客户端的登陆请求被服务端认证失败后的回调（事件通知于登陆/认证失败后）。
说明：补充说明：登陆/认证失败的原因可能是用户名、密码等不正确等，但具体逻辑由服务端的 callBack_checkAuthToken回调函数去处理。
推荐用法：开发者可在此回调中提示用户登陆IM服务器失败。。
参数1： {boolean}：true表示是掉线重连后的认证失败（在登陆其间可能用户的密码信息等发生了变更），否则表示首次登陆时的认证失败。

14）IMSDK.callback_onIMReconnectSucess()：

用途：由开发者设置的回调方法：掉线重连成功后的回调（事件通知于掉线重连成功后）。
推荐用法：开发者可在此回调中处理掉线重连成功后的界面状态更新等，比如设置将界面上的“离线”文字更新成“在线”。

15）IMSDK.callback_onIMDisconnected()：

用途：由开发者设置的回调方法：网络连接已断开时的回调（事件通知于与服务器的网络断开后）。
推荐用法：开发者可在此回调中处理掉线时的界面状态更新等，比如设置将界面上的“在线”文字更新成“离线”。

16）IMSDK.callback_onIMPing()：

用途：由开发者设置的回调方法：本地发出心跳包后的回调通知（本回调并非MobileIMSDK-微信小程序端核心逻辑，开发者可以不需要实现！）。
推荐用法：开发者可在此回调中处理底层网络的活动情况。

17）IMSDK.callback_onIMPong()：

用途：由开发者设置的回调方法：收到服务端的心跳包反馈的回调通知（本回调并非MobileIMSDK-微信小程序端核心逻辑，开发者可以不需要实现！）。
推荐用法：开发者可在此回调中处理底层网络的活动情况。

18）IMSDK.callback_onIMShowAlert(alertContent)：

用途：由开发者设置的回调方法：框架层的一些提示信息显示回调（本回调并非MobileIMSDK-微信小程序端核心逻辑，开发者可以不需要实现！）。
说明：开发者不设置的情况下，框架默认将调用wx.showModal()显示提示信息，否则将使用开发者设置的回调——目的主要是给开发者自定义这种信息的UI显示，提升UI体验，别无它用】。
参数1：{String}：必填项，文本类型，表示提示内容。

19）IMSDK.callback_onIMKickout(kickoutInfo)：

用途：由开发者设置的回调方法：收到服务端的“踢出”指令（本回调并非MobileIMSDK-微信小程序端核心逻辑，开发者可以不需要实现！）。
参数1：{PKickoutInfo}：非空，详见：PKickoutInfo。

20）IMSDK.callback_onMessagesLost(lostMessages)：

用途：由开发者设置的回调方法：消息未送达的回调事件通知。
发生场景：比如用户刚发完消息但网络已经断掉了的情况下，表现形式如：就像手机qq或微信一样消息气泡边上会出现红色图标以示没有发送成功）。
建议用途：应用层可通过回调中的指纹特征码找到原消息并可以UI上将其标记为“发送失败”以便即时告之用户。
参数1：{Array<Protocal>}：由框架的QoS算法判定出来的未送达消息列表。

21）IMSDK.callback_onMessagesBeReceived(theFingerPrint)：

用途：由开发者设置的回调方法：消息已被对方收到的回调事件通知。
说明：目前，判定消息被对方收到是有两种可能：
- 1) 对方确实是在线并且实时收到了；
- 2) 对方不在线或者服务端转发过程中出错了，由服务端进行离线存储成功后的反馈（此种情况严格来讲不能算是“已被收到”，但对于应用层来说，离线存储了的消息原则上就是已送达了的消息：因为用户下次登陆时肯定能通过HTTP协议取到）。
建议用途：应用层可通过回调中的指纹特征码找到原消息并可以UI上将其标记为“发送成功”以便即时告之用户。
参数1：{String}：已被收到的消息的指纹特征码（唯一ID），应用层可据此ID找到原先已发的消息并可在UI是将其标记为”已送达“或”已读“以便提升用户体验。

五、如何接入SDK

5.1 如何引入SDK到您的微信小程序工程中？

很简单：只需要将第2节中提到的SDK所有JS文件复制到您的微信小程序工程下即可。

以下是SDK全部文件在工程中的路径和位置（以自带的Demo工程为例，如下图所示）：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_7.png

5.2 如何在代码中调用SDK？

第一步：引用SDK的接口主文件（具体例子详见Demo中的im-manager.js文件）
即时通讯框架MobileIMSDK的微信小程序端开发者手册_8.png

第二步：为SDK设置回调各种函数（具体例子详见Demo中的im-manager.js文件）
即时通讯框架MobileIMSDK的微信小程序端开发者手册_9.png

第三步：初始化SDK（具体例子详见Demo中的app.js文件）
即时通讯框架MobileIMSDK的微信小程序端开发者手册_10.png

注意：上图中登录连接的IP地址请设置为您的MobileIMSDK服务器地址哦。

第四步：在你的主界面或登陆界面中调用IM的登陆方法即可（具体例子详见Demo中的主界面main.js文件）
即时通讯框架MobileIMSDK的微信小程序端开发者手册_11.png

六、Demo运行方法（模拟器方式）

6.1 重要说明

MobileIMSDK的小程序端工程（包括Demo代码），不依赖任何第3方库，完全使用微信小程序官方标准API实现，所以你在拿到MobileIMSDK的小程序端工程后直接开箱即可运行，切莫搞复杂、不要私自加戏！

6.2 配置要连接的MobileIMSDK服务器IP

注意：下图中登陆连接的IP地址请设置为您自已的MobileIMSDK服务器地址哦。

友情提示： MobileIMSDK的服务端该怎么部署就不是本手册要讨论的内容了，你可以参见《即时通讯框架MobileIMSDK的Demo使用帮助：Server端》。

即时通讯框架MobileIMSDK的微信小程序端开发者手册_12.png

▲ 配置要连接的服务器IP（以上代码详见 /app.js文件）

6.3 取消域名校验

微信强制要求小程序必须拥有备案的域名及TLS证书，测试时关掉这个限制，否则无法运行哦（参见微信官方手册）。

取消域名校验的方法如下：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_13.png

6.4 编译整个工程

如下图所示，点击编译后，将自动在左边模拟器里显示自带的Demo界面：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_14.png

6.5 在模拟器中的运行效果

Demo的登陆界面运行截图：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_15.png

Demo的主界面运行截图：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_16.png

七、Demo运行方法（真机调试方式）

7.1 取消域名校验

微信强制要求小程序必须拥有备案的域名及TLS证书，测试时关掉这个限制，否则无法运行哦（参见微信官方手册）。

取消域名校验的方法如下：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_17.png

7.2 打开真机调试二维码

如下图所示，点击小虫子图标后将显示真机调试二维码（打开你的微信扫描这个二维码即可）：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_18.png

7.3 用微信扫描调试二维码

如下图所示，打开你的微信，扫描二维码后就可在真机上调试了：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_19.png

7.4 在真机调试模式下的运行效果

以下是真机调试实拍图：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_20.jpg

以下是真机运行功能说明图（拼合图）：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_21.jpg

八、常见问题（FAQ）

8.1 为什么控制台下有些log不显示？

原因是：微信开发工具中，控制台下的日志级别默认进行了过过滤，勾选所有日志级别，就能看到SDK的详细日志输出了。

勾选所有的日志输出级别：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_22.png

然后就能看到SDK中详细的日志输出了（就像下图这样），方便调试和研究：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_23.png

8.2 为什么调试时报错“域名不在合法的域名列表中”？

以下是报错信息截图：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_24.png

原因是：微信强制要求小程序必须拥有备案的域名及TLS证书，测试时关掉这个限制，否则无法运行哦（参见微信官方手册）。

解决方法是：关闭域名校验（如下图所示）：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_25.png

8.3 为什么真机调试时报“找不到log2目录”？

以下是报错信息截图：
即时通讯框架MobileIMSDK的微信小程序端开发者手册_26.png

如上图所示，报错信息是：“Error: accessSync:fail no such file or directory, access 'wxfile://usr/miniprogramLog/log2”。

原因：这是微信小程序开发工具的官方bug，可以不用理会这个问题。

九、引用资料

[1] 微信小程序官方开发者手册
[2] MobileIMSDK开源框架的API文档
[3] MobileIMSDK开源IM框架源码（Github地址点此）
[4] MobileIMSDK 的微信小程序端发布公告
[5] MobileIMSDK的微信小程序端基本介绍
[6] MobileIMSDK的微信小程序端的开发手册（* 精编PDF版）
[7] MobileIMSDK的Demo使用帮助：Server端
[8] 最全教程：微信小程序开发入门详解
[9] WebSocket从入门到精通，半小时就够！

2 楼: 大水冲了老龙王 · 12 个月前

大佬，请教一下微信小程序能使用 MobileIMSDK-Web 开发即时通讯功能吗？还是只能用MobileIMSDK的微信小程序端来开发？

3 楼: JackJiang · 12 个月前

引用：大水冲了老龙王发表于 2023-11-16 09:43
大佬，请教一下微信小程序能使用 MobileIMSDK-Web 开发即时通讯功能吗？还是只能用MobileIMSDK的微信小程序 ...

只能用MobileIMSDK的微信小程序端来开发

本文目录

一、理论知识准备

二、开发工具准备

三、SDK文件用途说明

3.1 文件概览

3.2 详细说明

四、主要API接口

4.1 主要API接口概览

4.2 主要API接口用途说明

五、如何接入SDK

5.1 如何引入SDK到您的微信小程序工程中？

5.2 如何在代码中调用SDK？

六、Demo运行方法（模拟器方式）

6.1 重要说明

6.2 配置要连接的MobileIMSDK服务器IP

6.3 取消域名校验

6.4 编译整个工程

6.5 在模拟器中的运行效果

七、Demo运行方法（真机调试方式）

7.1 取消域名校验

7.2 打开真机调试二维码

7.3 用微信扫描调试二维码

7.4 在真机调试模式下的运行效果

八、常见问题（FAQ）

8.1 为什么控制台下有些log不显示？

8.2 为什么调试时报错“域名不在合法的域名列表中”？

8.3 为什么真机调试时报“找不到log2目录”？

九、引用资料

本帖已收录至以下技术专辑

MobileIMSDK(v6.5精编版)

MobileIMSDK-Web(有偿开源)

RainbowAVnew(有偿开源)

RainbowChat(技术转让)

RainbowChat-Web(技术转让)

精华之王

白金版主

终身成就

即时通讯网

友情链接[友链交换]

关于

微信公众号new

MobileIMSDK (v6.5精编版)

MobileIMSDK-Web (有偿开源)

RainbowAVnew (有偿开源)

RainbowChat (技术转让)

RainbowChat-Web (技术转让)

即时通讯网　