► 相關鏈接：
一、理論知識準備
您需要對Uniapp和Vue開發有所了解：
您需要對WebSocket技術有所了解：
標準WebSocket協議文檔、API手冊：
Uniapp 的 WebSocket 文檔和手冊：
二、開發工具準備
1）HBuilderX：
（JackJiang 使用的版本號如下圖所示，為了方便直接引用工程，建議你也使用此版或較新版本）
2）一站式下載地址：HBuilderX官方下載地址點此進入。
3）HBuilderX效果預覽：
三、SDK 文件用途說明
3.1文件概覽
純 Uniapp 標準 JS API 實現，無任何第 3 方庫依賴，更無本地原生代碼混編：
MobileIMSDK-Uniapp 端 SDK 本身只是 JS 文件源碼的集合，自帶的 Demo 代碼只是為了方便隨時測試 SDK 代碼，目的主要是用于演示 SDK 的 API 調用，Demo 代碼不屬于 SDK 框架的一部分。
大致的目錄說明：
3.2詳細說明
SDK 各模塊/文件作用說明：
四、主要 API 接口
4.1主要 API 接口概覽
所有 SDK 接口均由/mobileimsdk/mobileimsdk-client-sdk.js 提供。以下是主要 API 接口概覽圖。
如下圖所示：接口設計跟 MobileIMSDK 的APP版一樣，均為高內聚和低侵入式的回調方式傳入業務層處理邏輯，無需（也不建議）開發者直接修改 sdk 級代碼。
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-Uniapp端核心算法層的log輸入，方便開發者調試。
- 參數enable ：{boolean} true表示開啟log輸出，否則不輸出，開發者不調用本函數的話系統默認是false（即不輸出log）。
7）IMSDK.setDebugSDKEnable(enable)：
- 用途：是否開啟MobileIMSDK-Uniapp端框架層的log輸入，方便開發者調試。
- 參數enable ：{boolean} true表示開啟log輸出，否則不輸出，開發者不調用本函數的話系統默認是false（即不輸出log）。
8）IMSDK.setDebugPingPongEnable(enable)：
- 用途：是否開啟MobileIMSDK-Uniapp端框架層的底層網絡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-Uniapp端核心邏輯，開發者可以不需要實現！）。
- 推薦用法 ：開發者可在此回調中處理底層網絡的活動情況。
17）IMSDK.callback_onIMPong()：
- 用途：由開發者設置的回調方法：收到服務端的心跳包反饋的回調通知（本回調并非MobileIMSDK-Uniapp端核心邏輯，開發者可以不需要實現！）。
- 推薦用法 ：開發者可在此回調中處理底層網絡的活動情況。
18）IMSDK.callback_onIMShowAlert(alertContent)：
- 用途：由開發者設置的回調方法：框架層的一些提示信息顯示回調（本回調并非MobileIMSDK-Uniapp端核心邏輯，開發者可以不需要實現！）。
- 說明 ：開發者不設置的情況下，框架默認將調用wx.showModal()顯示提示信息，否則將使用開發者設置的回調——目的主要是給開發者自定義這種信息的UI顯示，提升UI體驗，別無它用】。
- 參數1：{String}：必填項，文本類型，表示提示內容。
19）IMSDK.callback_onIMKickout(kickoutInfo)：
- 用途：由開發者設置的回調方法：收到服務端的“踢出”指令（本回調并非MobileIMSDK-Uniapp端核心邏輯，開發者可以不需要實現！）。
- 參數1 ：{PKickoutInfo}：非空，詳見：PKickoutInfo
20）IMSDK.callback_onMessagesLost(lostMessages)：
- 用途：由開發者設置的回調方法：消息未送達的回調事件通知。
- 發生場景 ：比如用戶剛發完消息但網絡已經斷掉了的情況下，表現形式如：就像手機qq或微信一樣消息氣泡邊上會出現紅色圖標以示沒有發送成功）。
- 建議用途：應用層可通過回調中的指紋特征碼找到原消息并可以UI上將其標記為“發送失敗”以便即時告之用戶。
- 參數1：{Array<rotocal>}：由框架的QoS算法判定出來的未送達消息列表。
21）IMSDK.callback_onMessagesBeReceived(theFingerPrint)：
- 用途：由開發者設置的回調方法：消息已被對方收到的回調事件通知。
- 說明 ：目前，判定消息被對方收到是有兩種可能：
- 1) 對方確實是在線并且實時收到了；
- 2) 對方不在線或者服務端轉發過程中出錯了，由服務端進行離線存儲成功后的反饋（此種情況嚴格來講不能算是“已被收到”，但對于應用層來說，離線存儲了的消息原則上就是已送達了的消息：因為用戶下次登陸時肯定能通過HTTP協議取到）。
- 建議用途：應用層可通過回調中的指紋特征碼找到原消息并可以UI上將其標記為“發送成功”以便即時告之用戶。
- 參數1：{String}：已被收到的消息的指紋特征碼（唯一ID），應用層可據此ID找到原先已發的消息并可在UI是將其標記為”已送達“或”已讀“以便提升用戶體驗。
五、如何接入SDK
5.1如何引入SDK到您的Uniapp工程中？
很簡單：只需要將第2節中提到的SDK所有JS文件復制到您的Uniapp工程下即可。
以下是SDK全部文件在工程中的路徑和位置（以自帶的Demo工程為例，如下圖所示）：
5.2如何在代碼中調用SDK？
第一步：引用SDK的接口主文件（具體例子詳見Demo中的im-manager.js文件）
- 第二步：為SDK設置回調各種函數（具體例子詳見Demo中的im-manager.js文件）
第三步：初始化SDK（具體例子詳見Demo中的main.js文件）
注意：上圖中登錄連接的IP地址請設置為您的MobileIMSDK服務器地址哦。
第四步：在你的主界面或登陸界面中調用IM的登陸方法即可（具體例子詳見Demo中的主界面index.vue文件）
六、Demo運行效果和功能說明
▲ 上圖是以iOS真機為例的運行截圖（其它設備運行效果請見本文檔后面的章節）
七、Demo運行方法（運行到瀏覽器中）
7.1重要說明
特別說明：MobileIMSDK的Uniapp端工程（包括Demo代碼），不依賴任何第3方庫，也不存在任何Native代碼混編，完全使用Uniapp官方標準API實現，所以你在拿到MobileIMSDK的Uniapp端工程后直接開箱即可運行，切莫搞復雜、不要私自加戲！
7.2配置要連接的MobileIMSDK服務器IP
注意：下圖中登陸連接的IP地址請設置為您自已的MobileIMSDK服務器地址哦。
友情提示： MobileIMSDK的服務端該怎么部署就不是本手冊要討論的內容了，你可以參見《即時通訊框架MobileIMSDK的Demo使用幫助：Server端》。
▲ 配置要連接的服務器IP（以上代碼詳見 /app.js文件）
7.3一鍵運行
如下圖所示，在彈出菜單中點擊“運行到內置瀏覽器”后，將自動在左邊模擬器里顯示自帶的Demo界面：
7.4在內置瀏覽器中的運行效果
1）Demo的登陸界面運行截圖：
2）Demo的主界面運行截圖：
3）Demo運行的同時，可以查看詳細的log輸出（方便調試）：
7.5在電腦瀏覽器中的運行效果（以Chrome為例）
1）Demo的登陸界面在Chrome中的運行截圖：
2）Demo的主界面在Chrome中的運行截圖：
八、Demo運行方法（運行到Android真機）
8.1選擇要運行的App基座
如下圖所示，在彈出菜單中點擊“運行到Android App基座”：
8.2選擇要運行的Android真機
如下圖所示，在彈出菜單中選擇已通過USB連接的Android手機并點擊“運行”：
8.3在Android真機上的運行效果
九、Demo運行方法（運行到iOS模擬器）
9.1 選擇要運行的App基座
如下圖所示，在彈出菜單中點擊“運行到iOS模擬器App基座”：
9.2選擇正在運行中的iOS模擬器
如下圖所示，在彈出菜單中選擇已通過XCode啟動的iOS模擬器并點擊“運行”：
9.3 在iOS模擬器上的運行效果
1）Demo運行完整截屏：
2）Demo運行實拍照片：
十、Demo運行方法（運行到iOS真機）
10.1選擇要運行的App基座
如下圖所示，在彈出菜單中點擊“運行到iOS App基座”：
10.2配置開發者證書簽名等
如下圖所示，在彈出菜單中點擊“使用Apple證書簽名”（以便配置好真機需要的開發者證書等信息）：
10.3選擇要運行的iOS真機
如下圖所示，在彈出菜單中選擇已通過USB連接的iOS真機并點擊“運行”：
10.4在iOS真機上的運行效果
十一、Demo運行方法（運行到微信小程序）
11.1選擇要導出的基座
如下圖所示，在彈出菜單中點擊“微信開發者工具”（它將自動生成微信小程序并自動找開微信開發者工具）：
11.2HBuilderX將自動生成微信小程序
1）HBuilder自動生成微信小程序成功時的控制臺日志信息輸出（有這樣的信息就表示生成成功了）：
2）HBuilder會自動打開微信小程序開發工具，并導入上一步中自動生成的微信小程序：
十二、Demo運行方法（運行到支付寶小程序）
12.1 選擇要導出的基座
如下圖所示，在彈出菜單中點擊“支付寶開發者工具”（它將自動生成支付寶小程序并自動找開支付寶開發工具）：
12.2HBuilderX將自動生成支付寶小程序
1）HBuilder自動生成支付寶小程序成功時的控制臺日志信息輸出（有這樣的信息就表示生成成功了）：
2）HBuilder會自動打開支付寶小程序開發工具，手動導入上一步中自動生成的支付寶小程序：
十三、常見問題（FAQ）
13.1為什么控制臺下有些log不顯示？
原因是：微信開發工具中，控制臺下的日志級別默認進行了過過濾，勾選所有日志級別，就能看到SDK的詳細日志輸出了。
勾選所有的日志輸出級別：
然后就能看到SDK中詳細的日志輸出了（就像下圖這樣），方便調試和研究：
13.2HBuilderX內置瀏覽器對css的mask-image支持存在bug
此Bug帶來的現象：當運行在HuilderX的內置瀏覽器中，滾動條出現時，圖標就變成了方塊了（mask-image屬性失效了）。
影響范圍：經反復測試，Android、ios、PC瀏覽器中都能正常運行，唯獨HuilderX的內置瀏覽器會出這個問題。
以下是Bug導致的問題截圖：
Bug上報地址：https://ask.dcloud.net.cn/question/168312
解決辦法：目前暫無解決辦法，只能等官方解決，好在只影響HBuilderX的內置瀏覽器，而內置瀏覽器除了偶爾用于調試預覽以外，并沒有更多用處，所以沒影響。此處特別寫出，只是讓開發者遇到此現象時不要困惑。
13.3HBuilderX生成的支付小程序代碼在WebSocket上存在bug
此Bug帶來的現象：當運行HBuilderX的生成的支付寶小程序時，一旦運行就會報“Cannot read properties of undefined (reading 'onOpen')”錯誤。進而無法完成網絡連接。
影響范圍：當于僅影響HBuilderX的生成的支付寶小程序。
以下是Bug導致的問題log信息：
Bug上報地址：https://ask.dcloud.net.cn/question/168947
解決辦法：目前暫無解決辦法，只能等官方解決，暫時測試時只影響了HBuilderX生成的支付寶小程序。
十四、引用資料
[1] Uniapp官方開發者手冊
[2] MobileIMSDK開源框架的API文檔
[3] MobileIMSDK開源IM框架源碼（Github地址點此）
[4] MobileIMSDK-Uniapp端發布公告
[5] MobileIMSDK-Uniapp端基本介紹
[6] MobileIMSDK-Uniapp端的開發手冊（* 精編PDF版）
[7] MobileIMSDK的Demo使用幫助：Server端
[8] WebSocket從入門到精通，半小時就夠！