JMessage Android 端開發詳解

目前愈來愈多的應用會須要集成即時通信功能，這裏就爲你們詳細講一下如何經過集成 JMessage 來爲你的 App 增長即時通信功能。

首先，一個最基礎的 IM 應用會須要有哪些功能？

• 用戶註冊/登陸

• 管理聊天會話

• 發送消息

• 接收消息

那麼咱們又該如何用 JMessage 來實現這些功能呢？

固然啦，你須要先爲本身的應用集成 JMessage SDK ，具體的集成方法能夠參考集成文檔，這裏就再也不重複啦。: )

下面咱們就來看看這些功能模塊具體應該怎樣開發？

在功能模塊開發以前，須要先調用 JMessageClient.init(applicationContext) 方法來初始化 SDK ，推薦在 Application 類中調用。

用戶註冊 / 登陸

註冊

JMessage 對於用戶的註冊，默認必需的只有用戶名和密碼，對於用戶名和密碼的要求以下：

|參數|字符說明|長度限制 | |:--------|:--------|:------| | username|以字母或者數字開頭。支持字母、數字、下劃線、英文點、減號、 @|Byte(4~128)| | password|不限 |Byte(4~128)|

用戶註冊方法：

JMessageClient.register(username, password, new BasicCallback() {
  @Override
  public void gotResult(int code, String desc) {
    if (code == 0) {
      // 註冊成功
    } else {
      // 註冊失敗。 status ：錯誤碼； desc ：錯誤描述
    }
  }
})

在你 App 的註冊界面調用該方法後，便將用戶註冊到了極光服務器，就不須要本身來維護，除此以外 JMessage 還提供了設置用戶暱稱（ nickname ）、生日（ birthday ）、個性簽名（ signature ）、性別（ gender ）、地區（ region ）和頭像（ avatar ）的方法。

詳情能夠參考相關 API 文檔。

登陸

在註冊成功後，註冊的用戶就能夠經過登陸 API 來進行登陸，以後便可以收發消息了。

登陸 API 的用法和註冊相似，你們能夠直接參考 API 文檔。

管理聊天會話

在 IM 應用中，聊天會話就是一個用戶同另外一個用戶 / 羣組的聊天關係。在 JMessage 中定義聊天會話的爲 Conversation 類。

像發送消息、獲取歷史消息、獲取會話中對方用戶的信息等和具體聊天會話相關的方法都存在於 Conversation 中。

首先，在 JMessage 中 Conversation 分爲單聊會話和羣聊會話。具體用法基本相同，只是有些地方須要你們注意下：

1. Conversation 中的 getTitle() 方法會返回聊天會話的標題，在不一樣狀況下會有不一樣的返回值：

   • 單聊會話：用戶有暱稱時顯示暱稱，沒有暱稱時顯示用戶名。

   • 羣聊會話：有羣名稱時顯示羣名稱，沒有時顯示羣中前五個用戶的名稱（相似 QQ 討論組）。

2. getTargetInfo() 會獲取會話中的目標對象信息，其返回值爲 Object ，須要根據具體狀況將其轉型爲 UserInfo 或 GroupInfo ，再分別處理。

3. 會話信息是保存在設備數據庫中的，所以若是用戶更換了設備，是沒法獲取歷史會話的。

4. 由於 JMessage 默認在收到聊天消息時會有通知提示，若是想要在進入和某個用戶 / 羣組的聊天界面後，再也不顯示該會話的通知提示，須要在進入會話界面時調用 JMessageClient.enterSingleConversation(username,appKey) 或 JMessageClient.enterGroupConversation(groupId)，退出聊天界面時則調用 JMessageClient.exitConversation() 來從新啓用對該會話的消息通知。
   發送消息

目前最新版本的 JMessage 支持文字、圖片、語音、位置、文件和自定義幾種類型的消息，基本的用法你們能夠直接參考 API 文檔，這裏就再也不贅述了。

這裏須要注意的是 JMessage 提供了兩種建立消息的方式：

1.JMessageClient.create*Message()
2.conversation.createSendMessage(MessageContent)

兩種方式的結果實際上是同樣的，都是返回一條建立好的 Message 對象。區別就在於若是你不光要發送消息，還須要 Conversation 對象的其餘方法，好比獲取對方的信息、頭像什麼的，那麼推薦使用第二種方法。若是僅僅是單獨的發消息，就能夠直接用第一種方法來建立。

建立完消息以後，就須要設置發送結果監聽了，代碼以下：

message.setOnSendCompleteCallback(new BasicCallback() {
@Override
public void gotResult(int responseCode, String responseDesc) {

if (responseCode == 0) {
  // 消息發送成功
} else {
  // 消息發送失敗
}

}
});
JMessageClient.sendMessage(message); // 以後再調用發送消息 API
下面講一下 JMessage 中幾種不一樣的消息類型，有什麼須要注意的小細節：

• JMessage 中的自定義消息（ Custom message ）與 JPush 中的自定義消息概念相似，當收到其餘用戶發送的自定義消息時是不會顯示通知欄提示的。

• 除去自定義消息，其餘的幾種消息在建立時是能夠指定 fromName 這個參數的，自定義的 fromName 將在消息接收方的通知欄做爲展現名展現出來，若是未設置則會依照用戶的暱稱 > 用戶名的優先級來展現。

• 在使用上面提到的第二種建立消息的方式時，參數 MessageContent 實際上是能夠添加附加字段的，附加字段不會顯示在通知欄中，由開發者本身決定取到附加字段後進行怎樣的操做。

接收消息

在瞭解發送消息後，下一步要作的固然就是接收消息啦。對於接受消息的代碼寫法，你們能夠參考開發指南文檔，這裏就再也不一一列舉了。

整體來講，接收消息的處理仍是很簡單的，參考開發文檔後基本寫法就能瞭解了。這裏講幾個須要注意的地方：

• 對於圖片消息，用戶在收到時， JMessage 默認會先下載一張縮略圖並緩存到本地，但這個過程是有可能失敗的，所以能夠判斷當消息狀態爲 receive_fail 時，再手動調用 downloadThumbnailImage 方法進行下載，代碼以下：

  switch (msg.getContentType()) {
  case image:

  ImageContent imageContent = (ImageContent) msg.getContent();
  if (msg.getStatus() == MessageStatus.receive_fail) {
    imageContent.downloadThumbnailImage(msg, new DownloadCompletionCallback() {        
      @Override        
      public void onComplete(int code, String desc, File file) {                    
        if (code == 0) {    
          // 下載成功
        } else {    
          // 下載失敗
        }
      }
    });
  }

  }

語音消息也是一樣，僅當自動下載失敗，消息狀態爲 receive_fail 時才須要手動調用 downloadVoiceFile 方法來下載。

• 圖片和文件消息附帶的文件，在收到消息後是不會自動下載文件附件的，須要開發者再調用另外的接口。分別是：

1. ImageContent.downloadOriginImage(Message, DownloadCompletionCallback)

2. FileContent.downloadFile(Message, DownloadCompletionCallback) 所以這兩種類型消息的 getLocalPath() 方法須要在上面的 API 調用完成後才能返回有效值。
   以上，就是使用 JMessage 開發一個基礎 IM 應用的步驟和一些值得注意的地方，快來試試吧。: )

若是您想要一個完整的項目參考，能夠戳這裏。

---

做者： Hevin - 極光（ JPush 爲極光團隊帳號，歡迎關注）

原文：JMessage Android 端開發詳解

知乎專欄：極光日報