mapleIM
简介：
maple-IM 为蓝蘑云推出的即时通讯消息系统，包括了聊天室聊天, 消息送礼, 单聊，群聊，黑名单，用户查询等功能，适用于娱乐，游戏，教育等实时IM场景中；Maple-IM支持快速私有化部署，一键部署上线。 使用 maple-IM 模块之前，请先 注册 蓝蘑云的开发者帐号并申请创建 AppId，可以在 开发者后台 获取 App ID 用于开发。
apiCloud即时通讯消息demo源码下载
演示的apiCloud demo源码自行前往github下载；
三：基本API说明
本模块包括以下接口类：
基础接口类：使用此类接口无需关心 UI 界面层，只需按照蓝蘑云的规范要求设计自己的代码逻辑即可。
监听事件类：包括所有底层回调给应用层的事件行为。
注意:
基础接口类
- initialize
- loginChatRoom
- logoutChatRoom
- sendMessage
- getRoomMemberCount
- getUserList
- muteUser
- kickoutUser
- 错误码说明
初始化函数(initialize)
初始化函数。
initialize({params})
注意事项:
- 如果在config.xml文件中配置了appId信息，那么在模块初始化的时候底层会自动调用此接口，无需再手动调用该接口。
params
appId:
- 类型：字符串
- 默认值：无
- 描述：蓝蘑云后台管理中的appId
示例代码
var mapleim = api.require('mapleIM');
mapleim.initialize({appId: "46712183****11"});
config.xml配置示例：
登录房间(loginChatRoom)
登录聊天室;
loginChatRoom({params}, callback(ret, err))
注意事项:
- 加入房间的用户账号必须在整个appId中唯一，相同的用户账号登录会被对方踢下线；
- 用户账号为字符串，长度为小于等于32个字符；
- 如果登录失败的话，SDK不会自动重连。但是在登录成功的情况下因为网络的问题或者其它问题导致的掉线，SDK底层会自动进行重连，直到登录成功或者开发者主动调用了logoutChatRoom();
params
roomId:
- 类型：字符串
- 默认值：无
- 描述：房间的唯一标识
account:
- 类型：字符串
- 默认值：无
- 描述：加入房间的用户账号
nickname:
- 类型：字符串
- 默认值：无
- 描述：登录用户的昵称
callback(ret, err)
ret:
- 类型：JSON对象
内部字段：
{
account:'', //登录的account
nickname:'', //登录用户昵称。
}
err:
- 类型：JSON对象
内部字段：
{
code:401, //错误的状态码
description:"APPID错误或者无效" //错误描述
}
示例代码
var mapleim = api.require('mapleIM');
mapleim.login({ roomId: '111', account: '111', nickname: 'nick'},function(ret, err) {
if( ret ){
alert( JSON.stringify( ret ) );
}else{
alert( JSON.stringify( err ) );
}
});
logoutChatRoom
退出聊天室登录，并断开连接，不再接收消息;
logoutChatRoom()
示例代码
var mapleim = api.require('mapleIM');
mapleim.logout();
sendMessage
发送自定义内容的消息
sendMessage({params}, callback(ret, err))
注意事项:
- SDK目前只支持纯文本内容的发送，但是消息的格式是可以自定义的，只要使用合适的格式，开发者很容易能够实现红包、点赞诸如此类的功能。
params
type:
- 类型：数字
- 默认值：1
- 描述：消息的类型。这个类型服务器不会做任何判断和处理，发送端填什么类型接收端收到的就是什么类型
text:
- 类型：字符串
- 默认值：无
- 描述：需要发送的通知内容。如果通知内容为空，此接口不会做任何事情
extra:
- 类型：字符串
- 默认值：无
- 描述：（可选项）额外信息文本
callback(ret, err)
ret:
- 描述：总是为空
err:
- 类型：JSON对象
- 描述：发送成功时为空，发送失败时不为空
内部字段：
{
code:401, //错误的状态码
description:"APPID错误或者无效" //错误描述
}
示例代码
var mapleim = api.require('mapleIM');
mapleim.sendMessage({type: 1, text: "text", extra: "extra"}, function(ret, err) {
if( err ){
alert( JSON.stringify( err ) );
}else{
alert( '发送成功' );
}
});
getRoomMemberCount
获取聊天室当前在线人数
getRoomMemberCount(callback(ret, err))
callback(ret, err)
ret:
- 类型：JSON对象
内部字段：
{
count:0, //聊天室人数
}
err:
- 类型：JSON对象
内部字段：
{
code:401, //错误的状态码
description:"验证失败" //错误描述
}
示例代码
var mapleim = api.require('mapleIM');
mapleim.getRoomMemberCount(function(ret, err) {
if( ret ){
alert( JSON.stringify( ret ) );
}else{
alert( JSON.stringify( err ) );
}
});
getUserList
获取聊天室用户列表
getUserList(param, callback(ret, err))
params
index:
- 类型：整数类型
- 默认值：无
- 描述：开始查询的位置
totoal:
- 类型：整数类型
- 默认值：无
- 描述：查询的人数
callback(ret, err)
ret:
- 类型：JSON对象
内部字段：
{
total:1, //实际查询到的总人数
entities:[
{"account":"123", //账户ID
"nickname":"445" //昵称
}
]
}
err:
- 类型：JSON对象
内部字段：
{
code:201, //错误的状态码
description:"用户未登录" //错误描述
}
示例代码
var mapleim = api.require('mapleIM');
mapleim.getUserList({index:1,total:20},function(ret, err) {
if( ret ){
alert( JSON.stringify( ret ) );
}else{
alert( JSON.stringify( err ) );
}
});
muteUser
对聊天室用户禁言
muteUser(params, callback(ret, err))
params
muted:
- 类型：布尔值
- 默认值：无
- 描述：true 禁止聊天，false 开始聊天
account:
- 类型：string
- 默认值：无
- 描述：被禁言者账号
callback(ret, err)
ret:
- 描述：总是为空
err:
- 类型：JSON对象
内部字段：
{
code:201, //错误的状态码
description:"用户未登录" //错误描述
}
示例代码
var mapleim = api.require('mapleIM');
mapleim.muteUser({muted:true, account:“abc”},function(ret, err) {
//
});
kickoutUser
将指定用户踢出聊天室
kickoutUser(params, callback(ret, err))
params
account:
- 类型：sting
- 默认值：无
- 描述：用户账号
callback(ret, err)
ret:
- 描述：总是为空
err:
- 类型：JSON对象
内部字段：
{
code:201, //错误的状态码
description:"用户未登录" //错误描述
}
示例代码
var mapleim = api.require('mapleIM');
kickoutUser({account:"abc"},function(ret, err) {
//
});
监听事件接口类
添加监听事件(addEventListener)
addEventListener({params}, callback(ret))
该方法用于添加mapleIM模块事件的监听
params
name:
- 类型：字符串
- 默认值：无
- 描述：sdk事件名称（详见事件）
callback(ret)
ret:
- 类型：JSON对象
- 描述：事件发生时回调的参数
示例代码
//监听收到其他用户消息
var maplertc = api.require('mapleIM');
maplertc.addEventListener({
name:'receiveMsg'
},function(ret){
//operation
});
移除事件监听(removeEventListener)
removeEventListener({params})
该方法用于移除事件监听；
params
name:
- 类型：字符串
- 默认值：无
- 描述：sdk事件名称（详见事件）
示例代码
var maplertc = api.require('mapleIM');
maplertc.removeEventListener({
name: 'receiveMsg'
});
移除所有的事件监听(removeAllEventListeners)
removeAllEventListeners()
该方法用于移除所有的事件监听；
示例代码
var maplertc = api.require('mapleIM');
maplertc.removeAllEventListeners();
监听事件
receiveMsg
收到新消息事件
callback(ret)
ret:
- 类型：JSON对象
- 描述：返回消息的具体内容，不为空
内部字段：
{
text:'' //消息的文本内容
sendId:'' //发送者的账号
sendName:'' //发送者昵称
extra:'' //消息的额外内容，可能为空
type:1 //消息类型。与发送端设置的消息类型一致
status:0 //消息状态。这个字段是本地维护的，收到的消息status均为0
}
示例代码
//监听收到消息的事件
mapleim.addEventListener({
name:'receiveMsg'
},function(ret,err){
//operation
});
disconnected
与服务器异常断开事件。用户主动断开连接不会触发此事件
callback()
不能为空
示例代码
//监听与服务器断开连接的事件
mapleim.addEventListener({
name:'disconnected'
},function(ret,err){
//operation
});
reconnecting
异常断开之后，sdk底层自动重连事件
callback()
不能为空
示例代码
//监听与服务器重连的事件
mapleim.addEventListener({
name:'reconnecting'
},function(ret,err){
//operation
});
reloginSuccess
sdk自动重连并登录服务器成功事件
callback()
不能为空
示例代码
//监听与服务器重连成功的事件
mapleim.addEventListener({
name:'reloginSuccess'
},function(ret,err){
//operation
});
reloginFailed
sdk尝试重新登录服务器失败事件
callback(ret)
ret:
- 类型：JSON对象
- 描述：返回登录失败的错误信息，不为空
内部字段：
{
code:-105 //错误的状态码
description:'' //错误的具体描述
}
示例代码
//监听与服务器重连失败的事件
mapleim.addEventListener({
name:'reloginFailed'
},function(ret,err){
//operation
});
forceLogout
账号在另外的设备登录，当前设备被强制踢下线事件
callback()
不能为空
示例代码
//监听用户被服务器踢下线的事件
mapleim.addEventListener({
name:'forceLogout'
},function(ret,err){
//operation
});
错误码说明
| 错误码 | 描述 |
|---|---|
| 200 | 成功 |
| 300 | 失败 |
| 401 | 验证失败 (appId无效) |
| 500 | 系统异常 |
| 507 | 用户被禁言 |
| 1005 | 消息内容和附加字段都为空 |
| 1009 | 已经被禁止登陆 |
| -101 | 数据解析出错 |
| -102 | 网络错误 |
| -103 | 获取服务器地址失败 |
| -104 | 当前没有登录 |
| -105 | 重连登录失败 |
| -106 | 超时 |