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 端开发详解

知乎专栏：极光日报