相關(guān)鏈接：

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

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

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

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

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

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

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

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

鴻蒙Next的WebSocket文檔和手冊(cè)：

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

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

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

1）DevEco-Studio：

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

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

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

三、SDK 文件用途說(shuō)明

3.1文件概覽

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

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

大致的目錄說(shuō)明：

3.2詳細(xì)說(shuō)明

SDK 各模塊/文件作用說(shuō)明：

四、主要API接口和用途說(shuō)明

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

1）ClientCoreSDK.getInstance().loginHasInit：

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

2）ClientCoreSDK.getInstance().connectedToServer：

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

3）ClientCoreSDK.getInstance().currentLoginInfo：

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

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

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

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

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

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

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

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

• 用途：發(fā)送注銷登陸信息。
• 說(shuō)明：此方法的調(diào)用將被本庫(kù)理解為退出庫(kù)的使用，本方法將會(huì)額外調(diào)用資源釋放方法 ClientCoreSDK#release() ，以保證資源釋放。本方法調(diào)用后，除非再次進(jìn)行登陸過(guò)程，否則核心庫(kù)將處于初始未初始化狀態(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機(jī)制支持，否則不需要。
• 參數(shù)fingerPrint：QoS機(jī)制中要用到的指紋碼（即消息包唯一id），可設(shè)為null，生成方法見(jiàn) Protocal.genFingerPrint()。
• 參數(shù)typeu：應(yīng)用層專用字段——用于應(yīng)用層存放聊天、推送等場(chǎng)景下的消息類型。注意：此值為-1時(shí)表示未定義。MobileIMSDK框架中，本字段為保留字段，不參與框架的核心算法，專留作應(yīng)用層自行定義和使用。
• 返回值：0表示數(shù)據(jù)發(fā)出成功，否則返回的是錯(cuò)誤碼，see ErrorCode。

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

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

10）SocketEvent.SOCKET_EVENT_ON_RECIEVE_MESSAGE事件通知：

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

11）SocketEvent.SOCKET_EVENT_ON_LOGIN_RESPONSE事件通知：

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

12）SocketEvent.SOCKET_EVENT_ON_LINK_CLOSE事件通知：

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

13）SocketEvent.SOCKET_EVENT_PING事件通知：

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

14）SocketEvent.SOCKET_EVENT_PONG事件通知：

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

15）SocketEvent.SOCKET_EVENT_KICKOUT事件通知：

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

16）SocketEvent.SOCKET_EVENT_ON_ERROR_RESPONSE事件通知：

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

17）SocketEvent.SOCKET_EVENT_RECONNECT_ATTEMPT事件通知：

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

18）SocketEvent.SOCKET_EVENT_MESSAGE_LOST事件通知：

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

19）SocketEvent.SOCKET_EVENT_MESSAGE_BE_RECIEVED事件通知：

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

五、如何引入SDK庫(kù)文件

5.1方法一：源碼形式

第一步：先將整個(gè)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或域名的（示例詳見(jiàn)Demo中的 IMClientManager.ets 文件）：

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

6.2第二步：初始化SDK

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

6.3第三步：注冊(cè)框架事件

注冊(cè)MobileIMSDK框架級(jí)的事件監(jiān)聽(tīng)（示例詳見(jiàn)Demo中的 IMClientManager.ets 文件）：

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

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

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

七、Demo運(yùn)行效果和功能說(shuō)明

八、Demo運(yùn)行方法

8.1重要說(shuō)明

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

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

注意：下圖中登陸連接的IP地址請(qǐng)?jiān)O(shè)置為您自已的MobileIMSDK服務(wù)器地址哦。

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

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

8.3啟動(dòng)模擬器

注意：如果沒(méi)有新建模擬器可以自已新建一個(gè)。另外也可以使用支持鴻蒙Next的真機(jī)，打開(kāi)“開(kāi)發(fā)者模式”并插入U(xiǎn)SB線即可使用。

▲ 點(diǎn)擊綠色箭頭，立即啟動(dòng)模擬器！

8.4一鍵運(yùn)行

如下圖所示，點(diǎn)擊綠色“運(yùn)行”按鈕后，將自動(dòng)在模擬器或真機(jī)里顯示自帶的Demo界面了：

8.5運(yùn)行效果

1）Demo的登陸界面運(yùn)行截圖：

2）Demo的主界面運(yùn)行截圖：

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

九、引用資料

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

[2] MobileIMSDK開(kāi)源框架的API文檔

[3] MobileIMSDK開(kāi)源IM框架源碼（Github地址點(diǎn)此）

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

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

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

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