[置頂]開源即時(shí)通訊IM框架MobileIMSDK的鴻蒙NEXT端開發(fā)快速入門

相關(guān)鏈接：

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

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

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

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

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

1）新手快速入門：WebSocket 簡明教程
2）WebSocket 詳解（一）：初步認(rèn)識(shí) WebSocket 技術(shù)
3）WebSocket 從入門到精通，半小時(shí)就夠！
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手冊(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)，相差不大。

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

1）DevEco-Studio：

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

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

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

三、SDK 文件用途說明

3.1文件概覽

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

MobileIMSDK-鴻蒙端SDK本身只是ets文件源碼的集合，自帶的Demo代碼只是為了方便隨時(shí)測(cè)試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ù)器后，本方法就會(huì)一直返回true（直到退出登陸IM）。
返回值：{boolean}，true表示已完成首次成功登陸（即已經(jīng)成功登陸過IM服務(wù)端了，后面掉線時(shí)不影響此標(biāo)識(shí)），否則表示尚未連接IM服務(wù)器。

2）ClientCoreSDK.getInstance().connectedToServer：

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

3）ClientCoreSDK.getInstance().currentLoginInfo：

用途：保存登陸時(shí)提交的登陸信息（用戶名、密碼/token等）。
說明：格式形如：{loginUserId:'',loginToken:''}，此返回值的內(nèi)容由調(diào)用登陸函數(shù) loginImpl()時(shí)傳入的內(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時(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ù)端。
說明：不同于其它IM框架，本框架的登錄和連接高度封裝在了一個(gè)sendLogin方法中，無需單獨(dú)再去connect服務(wù)器，大大簡化了SDK的使用。loginInfo登陸信息各字段定義見：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1697。

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

用途：發(fā)送注銷登陸信息。
說明：此方法的調(diào)用將被本庫理解為退出庫的使用，本方法將會(huì)額外調(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機(jī)制支持，否則不需要。
參數(shù)fingerPrint：QoS機(jī)制中要用到的指紋碼（即消息包唯一id），可設(shè)為null，生成方法見 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)見“/module/mb_constants.js”下的createCommonData函數(shù)說明。
返回值：0表示數(shù)據(jù)發(fā)出成功，否則返回的是錯(cuò)誤碼，see ErrorCode。

10）SocketEvent.SOCKET_EVENT_ON_RECIEVE_MESSAGE事件通知：

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

11）SocketEvent.SOCKET_EVENT_ON_LOGIN_RESPONSE事件通知：

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

13）SocketEvent.SOCKET_EVENT_PING事件通知：

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

14）SocketEvent.SOCKET_EVENT_PONG事件通知：

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

15）SocketEvent.SOCKET_EVENT_KICKOUT事件通知：

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

16）SocketEvent.SOCKET_EVENT_ON_ERROR_RESPONSE事件通知：

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

17）SocketEvent.SOCKET_EVENT_RECONNECT_ATTEMPT事件通知：

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

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)以示沒有發(fā)送成功）。
建議用途：應(yīng)用層可通過回調(diào)中的指紋特征碼找到原消息并可以UI上將其標(biāo)記為“發(fā)送失敗”以便即時(shí)告之用戶。
參數(shù)1：{Array}：由框架的QoS算法判定出來的未送達(dá)消息列表。

19）SocketEvent.SOCKET_EVENT_MESSAGE_BE_RECIEVED事件通知：

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

五、如何引入SDK庫文件

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或域名的（示例詳見Demo中的 IMClientManager.ets 文件）：

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

6.2第二步：初始化SDK

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

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

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

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

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

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

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

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

8.1重要說明

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