mapleIM

立即使用

简介:

maple-IM 为蓝蘑云推出的即时通讯消息系统,包括了聊天室聊天, 消息送礼, 单聊,群聊,黑名单,用户查询等功能,适用于娱乐,游戏,教育等实时IM场景中;Maple-IM支持快速私有化部署,一键部署上线。 使用 maple-IM 模块之前,请先 注册 蓝蘑云的开发者帐号并申请创建 AppId,可以在 开发者后台 获取 App ID 用于开发。


apiCloud即时通讯消息demo源码下载

演示的apiCloud demo源码自行前往github下载;


三:基本API说明

本模块包括以下接口类:

  1. 基础接口类:使用此类接口无需关心 UI 界面层,只需按照蓝蘑云的规范要求设计自己的代码逻辑即可。

  2. 监听事件类:包括所有底层回调给应用层的事件行为。

注意:

基础接口类

初始化函数(initialize)

初始化函数。

initialize({params})

注意事项:

  • 如果在config.xml文件中配置了appId信息,那么在模块初始化的时候底层会自动调用此接口,无需再手动调用该接口。

params

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