一、理論知識準備

您需要對微信小程序開發(fā)有所了解：

• 1）真正零基礎入門學習筆記系列
• 2）從零開始的微信小程序入門教程
• 3）最全教程：微信小程序開發(fā)入門詳解

您需要對Websocket技術有所了解：

• 1）新手快速入門：WebSocket簡明教程
• 2）WebSocket詳解（一）：初步認識WebSocket技術
• 3）WebSocket從入門到精通，半小時就夠！
• 4）從零理解WebSocket的通信原理、協(xié)議格式、安全性

標準WebSocket協(xié)議文檔、API手冊：

• 1）WebSocket的API手冊
• 2）WebSocket的RFC標準文檔

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

• 1）微信官方WebSocket文檔鏈接

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

二、開發(fā)工具準備

1）微信小程序開發(fā)工具：

（JackJiang使用的版本號如上圖所示，為了方便直接引用工程，建議你也使用此版或較新版本）

2）一站式下載地址：微信官方下載地址點此進入。

3）微信小程序開發(fā)工具效果預覽：

三、SDK文件用途說明

3.1 文件概覽

純微信標準JS API實現(xiàn)，無任何第3方庫依賴：

MobileIMSDK-微信小程序端SDK本身只是JS文件源碼的集合，自帶的Demo代碼只是為了方便隨時測試SDK代碼，目的主要是用于演示SDK的API調用，Demo代碼不屬于SDK框架的一部分。

大致的目錄說明：

3.2 詳細說明

SDK各模塊/文件作用說明：

四、主要API接口

4.1 主要API接口概覽

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

以下是主要API接口概覽圖：

如下圖所示：接口設計跟MobileIMSDK的APP版一樣，均為高內聚和低侵入式的回調方式傳入業(yè)務層處理邏輯，無需（也不建議）開發(fā)者直接修改SDK級代碼。

4.2 主要API接口用途說明

1）IMSDK.isLogined()：

• 用途：是否已經(jīng)完成過首次登陸。
• 說明 ：用戶一旦從自已的應用中完成登陸IM服務器后，本方法就會一直返回true（直到退出登陸IM）。
• 返回值：{boolean}，true表示已完成首次成功登陸（即已經(jīng)成功登陸過IM服務端了，后面掉線時不影響此標識），否則表示尚未連接IM服務器。

2）IMSDK.isOnline()：

• 用途：是否在線。
• 說明：表示網(wǎng)絡連接是否正常。
• 返回值：{boolean}，true表示網(wǎng)絡連接正常，否則表示已掉線，本字段只在this._logined=true時有意義（如果都沒有登陸到IM服務器，怎么存在在線或掉線的概念呢）。

3）IMSDK.getLoginInfo()：

• 用途 ：返回登陸時提交的登陸信息（用戶名、密碼/token等）。
• 說明 ：格式形如：{loginUserId:'',loginToken:''}，此返回值的內容由調用登陸函數(shù) loginImpl()時傳入的內容決定。字段定義詳見：PLoginInfo。
• 返回值：{boolean}，true表示網(wǎng)絡連接正常，否則表示已掉線，本字段只在this._logined=true時有意義（如果都沒有登陸到IM服務器，怎么存在在線或掉線的概念呢）。

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

• 用途：向某人發(fā)送一條消息。
• 參數(shù)p：{Protocal} 要發(fā)送的消息協(xié)議包對象，Protocal詳情請見“/module/mb_constants.js”下的createCommonData函數(shù)說明。
• 參數(shù)fnSuccess ：{function} 接口調用成功的回調函數(shù)，非必填項
• 參數(shù)fnFail ：{function} 接口調用失敗的回調函數(shù)，非必填項
• 參數(shù)fnComplete ：{function} 接口調用結束的回調函數(shù)（調用成功、失敗都會執(zhí)行），非必填項
• 返回值：{int} 0表示成功，否則表示錯誤碼，錯碼詳見“/module/mb_constants.js”下的MBErrorCode對象屬性說明。

5）IMSDK.disconnectSocket()：

• 用途：客戶端主動斷開客戶端socket連接。
• 說明：當開發(fā)者登陸IM后，需要退出登陸時，調用本函數(shù)就對了，本函數(shù)相當于登陸函數(shù) loginImpl()的逆操作。

6）IMSDK.setDebugCoreEnable(enable)：

• 用途：是否開啟MobileIMSDK-微信小程序端核心算法層的log輸入，方便開發(fā)者調試。
• 參數(shù)enable：{boolean} true表示開啟log輸出，否則不輸出，開發(fā)者不調用本函數(shù)的話系統(tǒng)默認是false（即不輸出log）。

7）IMSDK.setDebugSDKEnable(enable)：

• 用途：是否開啟MobileIMSDK-微信小程序端框架層的log輸入，方便開發(fā)者調試。
• 參數(shù)enable：{boolean} true表示開啟log輸出，否則不輸出，開發(fā)者不調用本函數(shù)的話系統(tǒng)默認是false（即不輸出log）。

8）IMSDK.setDebugPingPongEnable(enable)：

• 用途：是否開啟MobileIMSDK-微信小程序端框架層的底層網(wǎng)絡WebSocket心跳包的log輸出，方便開發(fā)者調試。
• 參數(shù)enable：{boolean} true表示開啟log輸出，否則不輸出，開發(fā)者不調用本函數(shù)的話系統(tǒng)默認是false（即不輸出log）。
• 注意：必須 setDebugEnable(true) 且 setDebugPingPongEnable(true) 時，心跳log才會真正輸出，方便控制。
• 返回值：true表示開啟log輸出，否則不輸出，開發(fā)者不調用本函數(shù)的話系統(tǒng)默認是false（即不輸出log）。

9）IMSDK.loginImpl(varloginInfo, wsUrl)：

• 用途：登陸/連接MobileIMSDK服務器時調用的方法。
• 說明：登陸/連接MobileIMSDK服務器由本函數(shù)發(fā)起
• 參數(shù)varloginInfo：{PLoginInfo} 必填項，登陸要提交給Websocket服務器的認證信息，不可為空，對象字段定義見：PLoginInfo
• 參數(shù)wsUrl：{string} 必填項：要連接的Websocket服務器地址，不可為空，形如：wss://yousite.net:3000/websocket。

10）IMSDK.callback_onIMLog(message, toConsole)：

• 用途：由開發(fā)者設置的回調方法：用于debug的log輸出。
• 推薦用法：開發(fā)者可在此回調中按照自已的意圖打印MobileIMSDK微信小程序端框架中的log，方便調試時使用。
• 參數(shù)1： {String}：必填項，字符串類型，表示log內容。
• 參數(shù)2： {boolean}：選填項，true表示輸出到console，否則默認方式(由開發(fā)者設置的回調決定)。

11）IMSDK.callback_onIMData(p, options)：

• 用途 ：由開發(fā)者設置的回調方法：用于收到聊天消息時在UI上展現(xiàn)出來（事件通知于收到IM消息時）。
• 推薦用法：開發(fā)者可在此回調中處理收到的各種IM消息。
• 參數(shù)1： {Protocal}：詳情請見“/module/mb_constants.js”下的Protocal類定義)。

12）IMSDK.callback_onIMAfterLoginSucess()：

• 用途：由開發(fā)者設置的回調方法：客戶端的登陸請求被服務端成功認證完成后的回調（事件通知于 登陸/認證 成功后）。
• 推薦用法：開發(fā)者可在此回調中進行登陸IM服務器成功后的處理。

13）IMSDK.callback_onIMAfterLoginFailed(isReconnect)：

• 用途：由開發(fā)者設置的回調方法：客戶端的登陸請求被服務端認證失敗后的回調（事件通知于 登陸/認證 失敗后）。
• 說明：補充說明：登陸/認證失敗的原因可能是用戶名、密碼等不正確等，但具體邏輯由服務端的 callBack_checkAuthToken回調函數(shù)去處理。
• 推薦用法：開發(fā)者可在此回調中提示用戶登陸IM服務器失敗。。
• 參數(shù)1： {boolean}：true表示是掉線重連后的認證失?。ㄔ诘顷懫溟g可能用戶的密碼信息等發(fā)生了變更），否則表示首次登陸時的認證失敗。

14）IMSDK.callback_onIMReconnectSucess()：

• 用途：由開發(fā)者設置的回調方法：掉線重連成功后的回調（事件通知于掉線重連成功后）。
• 推薦用法：開發(fā)者可在此回調中處理掉線重連成功后的界面狀態(tài)更新等，比如設置將界面上的“離線”文字更新成“在線”。

15）IMSDK.callback_onIMDisconnected()：

• 用途：由開發(fā)者設置的回調方法：網(wǎng)絡連接已斷開時的回調（事件通知于與服務器的網(wǎng)絡斷開后）。
• 推薦用法：開發(fā)者可在此回調中處理掉線時的界面狀態(tài)更新等，比如設置將界面上的“在線”文字更新成“離線”。

16）IMSDK.callback_onIMPing()：

• 用途 ：由開發(fā)者設置的回調方法：本地發(fā)出心跳包后的回調通知（本回調并非MobileIMSDK-微信小程序端核心邏輯，開發(fā)者可以不需要實現(xiàn)?。?。
• 推薦用法：開發(fā)者可在此回調中處理底層網(wǎng)絡的活動情況。

17）IMSDK.callback_onIMPong()：

• 用途：由開發(fā)者設置的回調方法：收到服務端的心跳包反饋的回調通知（本回調并非MobileIMSDK-微信小程序端核心邏輯，開發(fā)者可以不需要實現(xiàn)?。?/span>
• 推薦用法：開發(fā)者可在此回調中處理底層網(wǎng)絡的活動情況。

18）IMSDK.callback_onIMShowalert(alertContent)：

• 用途：由開發(fā)者設置的回調方法：框架層的一些提示信息顯示回調（本回調并非MobileIMSDK-微信小程序端核心邏輯，開發(fā)者可以不需要實現(xiàn)?。?/span>
• 說明：開發(fā)者不設置的情況下，框架默認將調用wx.showModal()顯示提示信息，否則將使用開發(fā)者設置的回調——目的主要是給開發(fā)者自定義這種信息的UI顯示，提升UI體驗，別無它用】。
• 參數(shù)1：{String}：必填項，文本類型，表示提示內容。

19）IMSDK.callback_onIMKickout(kickoutInfo)：

• 用途：由開發(fā)者設置的回調方法：收到服務端的“踢出”指令（本回調并非MobileIMSDK-微信小程序端核心邏輯，開發(fā)者可以不需要實現(xiàn)！）。
• 參數(shù)1：{PKickoutInfo}：非空，詳見：PKickoutInfo。

20）IMSDK.callback_onMessagesLost(lostMessages)：

• 用途：由開發(fā)者設置的回調方法：消息未送達的回調事件通知。
• 發(fā)生場景：比如用戶剛發(fā)完消息但網(wǎng)絡已經(jīng)斷掉了的情況下，表現(xiàn)形式如：就像手機qq或微信一樣消息氣泡邊上會出現(xiàn)紅色圖標以示沒有發(fā)送成功）。
• 建議用途：應用層可通過回調中的指紋特征碼找到原消息并可以UI上將其標記為“發(fā)送失敗”以便即時告之用戶。
• 參數(shù)1：{Array}：由框架的QoS算法判定出來的未送達消息列表。

21）IMSDK.callback_onMessagesBeReceived(theFingerPrint)：

• 用途：由開發(fā)者設置的回調方法：消息已被對方收到的回調事件通知。
• 說明：目前，判定消息被對方收到是有兩種可能： – 1) 對方確實是在線并且實時收到了； – 2) 對方不在線或者服務端轉發(fā)過程中出錯了，由服務端進行離線存儲成功后的反饋（此種情況嚴格來講不能算是“已被收到”，但對于應用層來說，離線存儲了的消息原則上就是已送達了的消息：因為用戶下次登陸時肯定能通過HTTP協(xié)議取到）。
• 建議用途：應用層可通過回調中的指紋特征碼找到原消息并可以UI上將其標記為“發(fā)送成功”以便即時告之用戶。
• 參數(shù)1：{String}：已被收到的消息的指紋特征碼（唯一ID），應用層可據(jù)此ID找到原先已發(fā)的消息并可在UI是將其標記為”已送達“或”已讀“以便提升用戶體驗。

五、如何接入SDK

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

很簡單：只需要將第2節(jié)中提到的SDK所有JS文件復制到您的微信小程序工程下即可。

以下是SDK全部文件在工程中的路徑和位置（以自帶的Demo工程為例，如下圖所示）：

5.2 如何在代碼中調用SDK？

第一步：引用SDK的接口主文件（具體例子詳見Demo中的im-manager.js文件）

第二步：為SDK設置回調各種函數(shù)（具體例子詳見Demo中的im-manager.js文件）

第三步：初始化SDK（具體例子詳見Demo中的app.js文件）

注意：上圖中登錄連接的IP地址請設置為您的MobileIMSDK服務器地址哦。

第四步：在你的主界面或登陸界面中調用IM的登陸方法即可（具體例子詳見Demo中的主界面main.js文件）

六、Demo運行方法（模擬器方式）

6.1 重要說明

MobileIMSDK的小程序端工程（包括Demo代碼），不依賴任何第3方庫，完全使用微信小程序官方標準API實現(xiàn)，所以你在拿到MobileIMSDK的小程序端工程后直接開箱即可運行，切莫搞復雜、不要私自加戲！

6.2 配置要連接的MobileIMSDK服務器IP

注意：下圖中登陸連接的IP地址請設置為您自已的MobileIMSDK服務器地址哦。

友情提示： MobileIMSDK的服務端該怎么部署就不是本手冊要討論的內容了，你可以參見《即時通訊框架MobileIMSDK的Demo使用幫助：Server端》。

▲ 配置要連接的服務器IP（以上代碼詳見 /app.js文件）

6.3取消域名校驗

微信強制要求小程序必須擁有備案的域名及TLS證書，測試時關掉這個限制，否則無法運行哦（參見微信官方手冊）。

取消域名校驗的方法如下：

6.4編譯整個工程

如下圖所示，點擊編譯后，將自動在左邊模擬器里顯示自帶的Demo界面：

6.5在模擬器中的運行效果

Demo的登陸界面運行截圖：

Demo的主界面運行截圖：

七、Demo運行方法（真機調試方式）

7.1 取消域名校驗

微信強制要求小程序必須擁有備案的域名及TLS證書，測試時關掉這個限制，否則無法運行哦（參見微信官方手冊）。

取消域名校驗的方法如下：

7.2 打開真機調試二維碼

如下圖所示，點擊小蟲子圖標后將顯示真機調試二維碼（打開你的微信掃描這個二維碼即可）：

7.3 用微信掃描調試二維碼

如下圖所示，打開你的微信，掃描二維碼后就可在真機上調試了：

7.4 在真機調試模式下的運行效果

以下是真機調試實拍圖：

以下是真機運行功能說明圖（拼合圖）：

八、常見問題（FAQ）

8.1 為什么控制臺下有些log不顯示？

原因是：微信開發(fā)工具中，控制臺下的日志級別默認進行了過過濾，勾選所有日志級別，就能看到SDK的詳細日志輸出了。

勾選所有的日志輸出級別：

然后就能看到SDK中詳細的日志輸出了（就像下圖這樣），方便調試和研究：

8.2 為什么調試時報錯“域名不在合法的域名列表中”？

以下是報錯信息截圖：

原因是：微信強制要求小程序必須擁有備案的域名及TLS證書，測試時關掉這個限制，否則無法運行哦（參見微信官方手冊）。

解決方法是：關閉域名校驗（如下圖所示）：

8.3 為什么真機調試時報“找不到log2目錄”？

以下是報錯信息截圖：

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

原因：這是微信小程序開發(fā)工具的官方bug，可以不用理會這個問題。

九、引用資料

[1] 微信小程序開發(fā)者手冊

[2] MobileIMSDK開源框架的API文檔

[3] MobileIMSDK開源IM框架源碼（Github地址點此）

[4] 開源輕量級 IM 框架 MobileIMSDK 的微信小程序端已發(fā)布

[5] 即時通訊框架MobileIMSDK的微信小程序端基本介紹

[6] 即時通訊框架MobileIMSDK的Demo使用幫助：Server端

[7] 最全教程：微信小程序開發(fā)入門詳解

[8] WebSocket從入門到精通，半小時就夠！

（本文已同步發(fā)布于：http://www.52im.net/thread-4168-1-1.html）