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 | 超时 |