相關(guān)鏈接：

• ① MobileIMSDK-鴻蒙端的詳細(xì)介紹
• ② MobileIMSDK-鴻蒙端的開發(fā)手冊new（* 精編PDF版）

一、理論知識準(zhǔn)備

您需要對鴻蒙Next和ArkTS開發(fā)有所了解：

• 1）HarmonyOS NEXT星河版零基礎(chǔ)入門到實戰(zhàn)（B站視頻）
• 2）零基礎(chǔ)快速上手HarmonyOS ArkTS開發(fā)（系列文章）
• 3）HarmonyOS 第一課（鴻蒙官方視頻教程）

您需要對WebSocket技術(shù)有所了解：

• 1）新手快速入門：WebSocket 簡明教程
• 2）WebSocket 詳解（一）：初步認(rèn)識 WebSocket 技術(shù)
• 3）WebSocket 從入門到精通，半小時就夠！
• 4）從零理解 WebSocket 的通信原理、協(xié)議格式、安全性
• 5）WebSocket詳解（二）：技術(shù)原理、代碼演示和應(yīng)用案例
• 6）WebSocket詳解（三）：深入WebSocket通信協(xié)議細(xì)節(jié)
• 7）WebSocket詳解（四）：刨根問底HTTP與WebSocket關(guān)系(上)
• 8）WebSocket詳解（五）：刨根問底HTTP與WebSocket關(guān)系(下)
• 9）WebSocket詳解（六）：刨根問底WebSocket與Socket的關(guān)系

HTML5的標(biāo)準(zhǔn)WebSocket協(xié)議文檔、API手冊：

• 1）WebSocket 的 API 手冊
• 2）WebSocket 的標(biāo)準(zhǔn)文檔

鴻蒙Next的WebSocket文檔和手冊：

• 1）鴻蒙Next的WebSocket官方文檔

小提示：鴻蒙Next中的WebSocket API跟標(biāo)準(zhǔn)HTML5中的WebSocket接口及用法略有不同，但主要API都能一一對應(yīng)，相差不大。

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

1）DevEco-Studio：

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

2）一站式下載地址：鴻蒙官網(wǎng)下載地址 點此進(jìn)入。（需要注冊成為開發(fā)者才能下載喲！）

3）DevEco-Studio效果預(yù)覽：

三、SDK 文件用途說明

3.1文件概覽

純ArkTS實現(xiàn)，無任何第3方庫依賴，更無本地原生代碼混編：

MobileIMSDK-鴻蒙端SDK本身只是ets文件源碼的集合，自帶的Demo代碼只是為了方便隨時測試SDK代碼，目的主要是用于演示SDK的API調(diào)用，Demo代碼不屬于SDK框架的一部分。

大致的目錄說明：

3.2詳細(xì)說明

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

四、主要API接口和用途說明

* 主要API文檔地址是：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/

1）ClientCoreSDK.getInstance().loginHasInit：

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

2）ClientCoreSDK.getInstance().connectedToServer：

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

3）ClientCoreSDK.getInstance().currentLoginInfo：

• 用途：保存登陸時提交的登陸信息（用戶名、密碼/token等）。
• 說明 ：格式形如：{loginUserId:'',loginToken:''}，此返回值的內(nèi)容由調(diào)用登陸函數(shù) loginImpl()時傳入的內(nèi)容決定。字段定義詳見：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1697l。

4）ClientCoreSDK.getInstance().init(eventHub: common.EventHub): void：

• 用途：初始化SDK核心。
• 說明：不同于MobileIMSDK的iOS和Java客戶端，本方法需要由開發(fā)者調(diào)用，以確保MobileIMSDK核心已被初始化完成。
• 本方法被調(diào)用后， #isInitialed() 將返回true，否則返回false。

5）ClientCoreSDK.getInstance().release(): void：

• 用途：保釋放MobileIMSDK框架資源統(tǒng)一方法。
• 說明 ：本方法建議在退出登陸（或退出APP時）時調(diào)用。調(diào)用時將嘗試關(guān)閉所有MobileIMSDK框架的后臺守護(hù)線程并同設(shè)置核心框架init=false、loginHasInit=false、connectedToServer=false。

6）LocalDataSender.getInstance().sendLogin(loginInfo: PLoginInfo | undefined): number：

• 用途：發(fā)送登陸(連接)信息給服務(wù)端。
• 說明 ：不同于其它IM框架，本框架的登錄和連接高度封裝在了一個sendLogin方法中，無需單獨再去connect服務(wù)器，大大簡化了SDK的使用。loginInfo登陸信息各字段定義見：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1697。

7）LocalDataSender.getInstance().sendLoginout(): number：

• 用途：發(fā)送注銷登陸信息。
• 說明：此方法的調(diào)用將被本庫理解為退出庫的使用，本方法將會額外調(diào)用資源釋放方法 ClientCoreSDK#release() ，以保證資源釋放。本方法調(diào)用后，除非再次進(jìn)行登陸過程，否則核心庫將處于初始未初始化狀態(tài)。

8）LocalDataSender.getInstance().sendCommonDataPlain(dataContentWidthStr: string, to_user_id: string, QoS: boolean = true, fingerPrint: string = '', typeu: number = -1): number：

• 用途：向某人發(fā)送一條消息。
• 參數(shù)dataContentWidthStr：要發(fā)送的數(shù)據(jù)內(nèi)容（字符串方式組織）。
• 參數(shù)to_user_id：要發(fā)送到的目標(biāo)用戶id。
• 參數(shù)QoS ：true表示需QoS機制支持，否則不需要。
• 參數(shù)fingerPrint：QoS機制中要用到的指紋碼（即消息包唯一id），可設(shè)為null，生成方法見 Protocal.genFingerPrint()。
• 參數(shù)typeu：應(yīng)用層專用字段——用于應(yīng)用層存放聊天、推送等場景下的消息類型。注意：此值為-1時表示未定義。MobileIMSDK框架中，本字段為保留字段，不參與框架的核心算法，專留作應(yīng)用層自行定義和使用。
• 返回值：0表示數(shù)據(jù)發(fā)出成功，否則返回的是錯誤碼，see ErrorCode。

9）LocalDataSender.getInstance().sendCommonData(p: Protocal): number：

• 用途：通用數(shù)據(jù)協(xié)議包的發(fā)送根方法。
• 參數(shù)p：{Protocal} 要發(fā)送的消息協(xié)議包對象，Protocal詳情請見“/module/mb_constants.js”下的createCommonData函數(shù)說明。
• 返回值：0表示數(shù)據(jù)發(fā)出成功，否則返回的是錯誤碼，see ErrorCode。

10）SocketEvent.SOCKET_EVENT_ON_RECIEVE_MESSAGE事件通知：

• 用途：以便收到聊天消息時在UI上展現(xiàn)出來（事件通知于收到IM消息時）。
• 推薦用法 ：開發(fā)者可在此通知中處理收到的各種IM消息。
• 參數(shù)1： {Protocal}：詳情請見Protocal類定義：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1350。

11）SocketEvent.SOCKET_EVENT_ON_LOGIN_RESPONSE事件通知：

• 用途：本地用戶的登陸結(jié)果回調(diào)事件通知（此事件發(fā)生時表示客戶端已登陸/連接或重連完成）。
• 推薦用法：開發(fā)者可在此事件中處理登錄連接和掉線重連響應(yīng)反饋。
• 參數(shù)1： {PLoginInfoResponse}：API文檔詳見：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1434。

12）SocketEvent.SOCKET_EVENT_ON_LINK_CLOSE事件通知：

• 用途：與服務(wù)端的通信斷開的回調(diào)事件通知（此事件發(fā)生時表示客戶端已掉線）。
• 該消息只有在客戶端連接服務(wù)器成功之后網(wǎng)絡(luò)異常中斷之時觸發(fā)。導(dǎo)致與與服務(wù)端的通信斷開的原因有（但不限于）：無線網(wǎng)絡(luò)信號不穩(wěn)定、WiFi與2G/3G/4G/5G等同開情況下的網(wǎng)絡(luò)切換、手機系統(tǒng)的省電策略等。
• 推薦用法 ：開發(fā)者可在此通知中處理掉線時的界面狀態(tài)更新等，比如設(shè)置將界面上的“在線”文字更新成“離線”。

13）SocketEvent.SOCKET_EVENT_PING事件通知：

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

14）SocketEvent.SOCKET_EVENT_PONG事件通知：

• 用途：收到服務(wù)端的心跳包反饋的回調(diào)通知（本回調(diào)并非MobileIMSDK-鴻蒙端核心邏輯，開發(fā)者可以不需要實現(xiàn)?。?。
• 推薦用法 ：開發(fā)者可在此回調(diào)中處理底層網(wǎng)絡(luò)的活動情況。

15）SocketEvent.SOCKET_EVENT_KICKOUT事件通知：

• 用途：收到服務(wù)端反饋的錯誤信息指令（本回調(diào)并非MobileIMSDK-鴻蒙端核心邏輯，開發(fā)者可以不需要實現(xiàn)！）。
• 參數(shù)1：{PKickoutInfo}：非空，詳見：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1428。

16）SocketEvent.SOCKET_EVENT_ON_ERROR_RESPONSE事件通知：

• 用途：收到服務(wù)端反饋的錯誤信息指令（本回調(diào)并非MobileIMSDK-鴻蒙端核心邏輯，開發(fā)者可以不需要實現(xiàn)！）。
• 參數(shù)1：{PErrorResponse}：非空，詳見：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1430。

17）SocketEvent.SOCKET_EVENT_RECONNECT_ATTEMPT事件通知：

• 用途：“自動重連嘗試中”事件（本回調(diào)并非MobileIMSDK-鴻蒙端核心邏輯，開發(fā)者可以不需要實現(xiàn)！）。
• 參數(shù) code ：{numeric}：0：已停止，1：持續(xù)運行中，2：單次脈搏

18）SocketEvent.SOCKET_EVENT_MESSAGE_LOST事件通知：

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

19）SocketEvent.SOCKET_EVENT_MESSAGE_BE_RECIEVED事件通知：

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

五、如何引入SDK庫文件

5.1方法一：源碼形式

第一步：先將整個sdk源碼module復(fù)制到您的鴻蒙工程中：

第二步：配置您的工程，確保正確引用了MobileIMSDK鴻蒙SDK的源碼module：

5.2方法二：.har包形式

第一步：先將MobileIMSDK鴻蒙端SDK的.har包放入您的鴻蒙Next主module中（比如新建的libs目錄下）：

第二步：配置您的工程，確保正確引用了MobileIMSDK鴻蒙SDK的.har包：

六、如何調(diào)用SDK代碼

6.1第一步：設(shè)置ws/wss連接URL

設(shè)置您自已部署的MobileIMSDK服務(wù)端IP或域名的（示例詳見Demo中的 IMClientManager.ets 文件）：

提示：MobileIMSDK的服務(wù)端Demo部署指南請見 http://www.52im.net/thread-63-1-1.html。

6.2第二步：初始化SDK

調(diào)用ClientCoreSDK中的init()方法進(jìn)行初始化（示例詳見Demo中的I MClientManager.ets 文件）：

6.3第三步：注冊框架事件

注冊MobileIMSDK框架級的事件監(jiān)聽（示例詳見Demo中的 IMClientManager.ets 文件）：

6.4第四步：調(diào)用登錄方法（框架內(nèi)部會自動啟動connect全過程）

調(diào)用登錄方法（示例詳見Demo中的 LoginPage.ets 文件）：

提示：不同于其它IM框架，本框架的登錄和連接高度封裝在了一個sendLogin方法中，無需單獨再去connect服務(wù)器，大大簡化了SDK的使用。

七、Demo運行效果和功能說明

八、Demo運行方法

8.1重要說明

特別說明：MobileIMSDK的鴻蒙端工程（包括Demo代碼），不依賴任何第3方庫，也不存在任何Native代碼混編，完全使用ArkTS、ArkUI官方標(biāo)準(zhǔn)API實現(xiàn)，所以你在拿到MobileIMSDK的鴻蒙端工程后直接開箱即可運行，切莫搞復(fù)雜、不要私自加戲！

8.2配置要連接的MobileIMSDK服務(wù)器IP

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

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

▲ 配置要連接的服務(wù)器IP（以上代碼詳見IMClientManager.ets文件）

8.3啟動模擬器

注意：如果沒有新建模擬器可以自已新建一個。另外也可以使用支持鴻蒙Next的真機，打開“開發(fā)者模式”并插入USB線即可使用。

▲ 點擊綠色箭頭，立即啟動模擬器！

8.4一鍵運行

如下圖所示，點擊綠色“運行”按鈕后，將自動在模擬器或真機里顯示自帶的Demo界面了：

8.5運行效果

1）Demo的登陸界面運行截圖：

2）Demo的主界面運行截圖：

3）Demo運行的同時，可以查看詳細(xì)的log輸出（方便調(diào)試）：

九、引用資料

[1] 鴻蒙Next官方開發(fā)資料

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

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

[4] MobileIMSDK-鴻蒙Next端發(fā)布公告

[5] MobileIMSDK-鴻蒙Next端詳細(xì)介紹

[6] MobileIMSDK-鴻蒙Next端開發(fā)手冊（* 精編PDF版）

[7] MobileIMSDK的Server端Demo使用幫助