V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
jpush
V2EX  ›  推广

JMessage Android 端开发详解

  •  
  •   jpush · 2017-03-31 17:54:19 +08:00 · 1269 次点击
    这是一个创建于 2794 天前的主题,其中的信息可能已经有所发展或是发生改变。

    目前越来越多的应用会需要集成即时通讯功能,这里就为大家详细讲一下如何通过集成 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 方法来下载。

    • 图片和文件消息附带的文件,在收到消息后是不会自动下载文件附件的,需要开发者再调用另外的接口。分别是:
      • ImageContent.downloadOriginImage(Message, DownloadCompletionCallback)
      • FileContent.downloadFile(Message, DownloadCompletionCallback) 因此这两种类型消息的 getLocalPath() 方法需要在上面的 API 调用完成后才能返回有效值。

    以上,就是使用 JMessage 开发一个基础 IM 应用的步骤和一些值得注意的地方,快来试试吧。: )

    如果您想要一个完整的项目参考,可以戳这里


    作者: Hevin - 极光( JPush 为极光团队账号,欢迎关注)

    原文:JMessage Android 端开发详解

    知乎专栏:极光日报

    目前尚无回复
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1095 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 24ms · UTC 18:46 · PVG 02:46 · LAX 10:46 · JFK 13:46
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.