快速入门

本文主要介绍如何将 RTM Android SDK 实时消息集成到你的项目中以及相关注意事项。

开发环境要求

下载最新版本 HBuilderX
下载示例 Demo 的压缩包。
一个有效的开发者账号。

快速集成

本小节介绍如何获取 AppID 以及如何快速将 SDK 集成到项目中。

获取 AppID

参考以下步骤获取一个 AppID。若已经拥有 AppID，请跳过当前步骤，直接查看快速集成。

1. 创建项目

首先我们需要在开发者控制台创建一个「项目」。
2. 获取 APP ID

获取项目的「APP ID」。

导入 SDK

操作流程

本节内容主要介绍如何实现点对点消息和频道消息的收发，提供相关示例代码。。

初始化客户端

在创建实例前，请确保你已完成环境准备，安装包获取等步骤。

创建实例需要填入准备好的 App ID, 只有 App ID 相同的应用才能互通。

指定事件回调 RtmClientListener，SDK 通过该回调通知应用程序：

SDK 与 RTM 系统的连接状态变化；
接收点对点消息；
其他相关事件。

setCallBack(){
    rtmModule.setCallBack((ret) =>{
        switch(ret.rtmEvent){
            case "onConnectionStateChanged":
                this.result.unshift("onConnectionStateChanged state="+ret.state+",reason ="+ret.reason);
                break;
            case "onPeerMessageReceived":
                this.result.unshift("收到来自："+ret.peerId+" 的消息："+ret.text);
                break;
            case "onPeersOnlineStatusChanged":
                this.result.unshift("peersStatus="+ret.peersStatus);
                break;
            case "onMemberCountUpdated":
                this.result.unshift("频道人员更新："+ret.memberCount);
                break;
            case "onAttributesUpdated":
                this.result.unshift("频道属性更新");
                break;
            case "onChannelMessageReceived":
                this.result.unshift(ret.userId+" 发来消息："+ret.text);
                break;
            case "onMemberJoined":
                this.result.unshift(ret.userId+"加入频道");
                break;
            case "onMemberLeft":
                this.result.unshift(ret.userId+"离开频道");
                break;
            default:
                break;
        }
    })
},
createInstance(){
    rtmModule.createInstance({
        //anyRTC 为 App 开发者签发的 App ID。每个项目都应该有一个独一无二的 App ID。如果你的开发包里没有 App ID，请从anyRTC官网(https://www.anyrtc.io)申请一个新的 App ID
        "appId":"YOUR APP ID"
    },(ret)=>{
        this.result.unshift("[createInstance] "+ret.code);
    })
},

替换 createInstance 方法中的 YOUR APP ID 字段，两台设备使用相同 App ID 的应用才能互相通信。

传入能标识用户角色和权限的 Token。如果安全要求不高，也可以将值设为 null。
传入能标识每个用户的 ID。用户 ID 为字符串，必须是可见字符（可以带空格），不能为空或者多于 64 个字符，也不能是字符串 "null"。
传入结果回调，用于接收登录 RTM 服务器成功或者失败的结果回调。

login(){
    rtmModule.login({
            "token":"",
            "userId":this.userId
        },(ret)=>{
            if(ret.code==0){
                this.result.unshift("登录成功！");
            }else{
                this.result.unshift("登录失败! errorCode="+reb.code);
            }
        })
},

点对点消息

点对点消息包括：发送点对点消息，接收点对点消息。

发送点对点消息

调用 sendMessageToPeer 方法发送点对点消息。在该方法中：

传入目标消息接收方的用户 ID 和传入的内容 text。
传入消息发送结果监听器，用于接收消息发送结果回调，如：服务器已接收，发送超时，对方不可达等。

rtmModule.sendMessageToPeer({
    "peerId":this.peerId,
    "text":this.ptoPMsg,
    "enableHistoricalMessaging":false,
    "enableOfflineMessaging":false
},(ret)=>{
    if(ret.code==0){
        this.result.unshift("发送消息成功!");
    }else{
        this.result.unshift("发送消息失败! errorCode="+ret.code);
    }
})

接收点对点消息

点对点消息的接收通过创建 Rtm 实例的时候传入的 setCallBack() 回调接口进行监听。在该回调接口的 onPeerMessageReceived 回调方法中：

text 是获取到消息文本内容。
peerId 是消息发送方的用户 ID。

频道消息

App 在成功登录 RTM 服务器之后，可以开始使用 RTM 的频道消息功能。

创建频道

创建频道和加入频道，channelId 该字符串长度在 64 字节以内。不能设为空、null，或 "null"。

rtmModule.createChannel({
        "channelId":this.channelId
    },(ret)=>{
        this.result.unshift("创建频道"+ (ret.code == 0 ? "成功！":"失败！") );
    });
    rtmModule.join({
        "channelId":this.channelId
    },(ret)=>{
        if(ret.code==0){
            this.result.unshift("加入频道!");
        }else{
            this.result.unshift("加入频道失败！errorCode="+ret.code);
        }
})

发送频道消息

在成功加入频道之后，用户可以开始向该频道发送消息。频道消息的接收通过创建频道消息的时候传入的回调接口进行监听。

调用频道实例的 sendChannelMessage() 方法向该频道发送消息。在该方法中：

传入 channelId 频道 ID， text 设置消息内容。enableHistoricalMessaging 是否保存为历史消息和 enableOfflineMessaging 是否设置为离线消息。
传入消息发送结果监听器，用于接收消息发送结果回调，如：服务器已接收，发送超时等。

rtmModule.sendChannelMessage({
        "channelId":this.channelId,
        "text":this.channelMsg,
        "enableHistoricalMessaging":false,
        "enableOfflineMessaging":false
    },(ret)=>{
        if(ret.code==0){
            this.result.unshift("发送频道消息成功!");
        }else{
            this.result.unshift("发送频道消息失败! errorCode="+ret.code);
        }
})

退出频道

调用实例的 leave() 方法可以退出该频道。channelRelease()方法可以释放该频道所有资源，leave() channelRelease()之后可以调用 join() 方法再重新加入频道。

登出

Rtm 的实例提供了 logout 方法可以登出 RTM 系统。

如果需要切换账号，可以在退出登录切换 uid 再次调用 login 实现切换账号。

logout(){
    rtmModule.logout((ret)=>{
        if(ret.code==0){
            this.result.unshift("登出成功！");
        }else{
            this.result.unshift("登出失败！ errorCode="+ret.code);
        }
    });
    rtmModule.release((ret)=>{
        this.result.unshift("release！code="+ret.code);
    })
}

开发注意事项

在收发点对点消息或进行其他频道操作前，请确保你已成功登录 RTM 系统。
使用频道核心功能前必须通过调用 createChannel 方法创建频道实例。
每个客户端实例最多只能同时加入 20 个频道。每个频道都应有不同的 channelId 参数。
当离开了频道且不再加入该频道时，可以调用 channelRelease 方法及时释放频道实例所占用的资源。