uexRongCloud查看3.0文档

1、简介

uexRongCloud(融云IM)插件

1.1、 说明

融云是国内首家专业的即时通讯云服务提供商,专注为互联网、移动互联网开发者提供免费的即时通讯基础能力和云端服务。通过融云平台,开发者不必搭建服务端硬件环境,就可以将即时通讯、实时网络能力快速集成至应用中。融云SDK包括两部分:IM界面组件和 IM通讯能力库。

本插件封装的是IM通讯能力库-IMLib,IMLib 是不含界面的基础 IM 通讯能力库,封装了通信能力和会话、消息等对象。

使用前说明:

该插件需要引擎3.3以上版本

本插件为单例插件 ——

• 在任何网页调用本插件,调用的是同一个插件实例;
• 所有的API都是异步方法,不会直接返回值;
• 所有的回调都会传到root页面(config.xml中配置的App起始页面)

以上内容非常重要

root页面收到回调后,可以通过uexWindow的相关方法传递到各个网页去, 以下方法是您可能要用到的——

 传递给某个窗口:
* uexWindow.evaluateScript;
* uexWindow.evaluatePopoverScript
* uexWindow.evaluateMultiPopoverScript

 传递给某些窗口:
* uexWindow.publishChannelNotification
* uexWindow.subscribeChannelNotification

这些方法具体用法在uexWindow文档 内有描述，当然,也可下载Demo 参考Demo内的调用。

1.2、 UI展示

暂无

1.3、 开源源码

插件测试用例与自定义插件下载:点击此处 (插件测试用例与插件源码已经提供)

参考4.0规范测试用例：点击下载

1.4、 术语表

Path Types

1.5、平台版本支持

本插件的所有API默认支持Android4.0+和iOS7.0+操作系统.
有特殊版本要求的API会在文档中额外说明.

1.6、接口有效性

本插件所有API默认在插件版本4.0.0+可用.
在后续版本中新添加的接口会在文档中额外说明.

2、API概述

使用该插件需要先在融云官网申请AppKey。 注意：Android 版本的AppKey需要在config.xml中配置,把value对应的值替换成自己的AppKey即可。示例如下:

<config desc="uexRongCloud" type="KEY">
    <param name="$uexRongCloud_APPKEY$" platform="Android" value="e5t4ouvptdhca"/>
</config>

2.1、初始化

init //初始化融云sdk

uexRongCloud.init(param,callback)

说明:

初始化融云sdk。 注意：Android 版本的AppKey需要在config.xml中配置,把value对应的值替换成自己的AppKey即可。

参数:

var param = {
    appKey:   
};

回调参数:

var callback = function (error,data){}

示例:

var param = {
      appKey:'bmdehs6pdprts'
  };
uexRongCloud.init(param,function(error,data){
    if(!error){
    alert("初始化成功")!
  }
});

2.2、登录与登出

写在前面：在您连接融云服务器之前，您需要请求您的 App Server，您的 App Server通过Server API 获取 Token 并返回给您的客户端，客户端获取到这个 Token 即可进入下一步连接融云服务器。可参考其官方文档

connect //与融云服务器建立连接

uexRongCloud.connect(param,callback)

说明:

与融云服务器建立连接。

注意：在App整个生命周期,您只需要调用一次此方法与融云服务器建立连接。之后无论是网络出现异常或者App有前后台的切换等,SDK都会负责自动重连。除非您已经手动将连接断开,否则您不需要自己再手动重连。

参数:

var param = {
    token:
};

回调参数:

var callback = function (error,data){}

示例:

var param = {
      token:'g3fqLjRWtJdOkUCd+uqMRFYLsaBj7tK6QZ9/KFrx+0H22Ki0yw2VryZSnIEN2vTPv9T56shgMwGSAC9SfCY27A=='
  };
uexRongCloud.connect(param,function(error,data){
     if(!error){
         alert("userId为:"+data)!
    }
});

disconnect //断开与融云服务器建立连接

uexRongCloud.disconnect(param)

说明:

断开与融云服务器建立连接。

注意：因为SDK在前后台切换或者网络出现异常都会自动重连,会保证连接的可靠性。 所以除非您的App逻辑需要登出,否则一般不需要调用此方法进行手动断开。

参数:

var param = {
    isReceivePush:
};

示例:

var param = {
      isReceivePush:false
  };
uexRongCloud.disconnect(param);

2.3、基础消息功能

写在前面：群组关系和群组列表由您的 App 维护，客户端的所有群组操作都需要请求您的 App Server， 您的 App Server 可以根据自己的逻辑进行管理和控制，然后通过 Server API 接口进行群组操作，并将结果返回给客户端。可参考其官方文档

sendMessage //发送消息

uexRongCloud.sendMessage(param,callback)

说明:

发送消息,包括文字消息、语音消息、图片消息、图文消息、位置消息、命令消息，并根据objectName字段区分。

参数:

var param = {

    ---公共参数---
    objectName:,
    conversationType:,
    targetId:,
    extra:,


     ---私有参数---
    //objectName 为"RC:TxtMsg"时(文字消息) 需要传以下参数
    text:,

    //objectName 为"RC:VcMsg"时(语音消息) 需要传以下参数
    voicePath:,  
    duration:,

    //objectName 为"RC:ImgMsg"时(图片消息) 需要传以下参数
    imgPath:, 

    //objectName 为"RC:ImgTextMsg"时(图文消息) 需要传以下参数
    title:, 
    description:, 
    imgPath:, 
    url: 

    //objectName 为"RC:LBSMsg"时(位置消息) 需要传以下参数
    latitude:, 
    longitude:, 
    poi:, 
    imgPath:, 

    //objectName 为"RC:CmdNtf"时(命令消息) 需要传以下参数
    name:, 
    data:, 

};

objectName 为"RC:TxtMsg"时(文字消息) 需要传以下参数:

objectName 为"RC:VcMsg"时(语音消息) 需要传以下参数:

objectName 为"RC:ImgMsg"时(图片消息) 需要传以下参数:

objectName 为"RC:ImgTextMsg"时(图文消息) 需要传以下参数:

objectName 为"RC:LBSMsg"时(位置消息) 需要传以下参数:

objectName 为"RC:CmdMsg"时(命令消息) 需要传以下参数:

回调参数:

var callback=function (status,messageId){}

示例:

var param = {
    objectName: "RC:ImgMsg",//发图片消息
    conversationType: "PRIVATE",
    targetId: "55666",
    extra: "extra info ...",  
    imgPath: 'res://img.png' //图片的本地路径
  };
  uexRongCloud.sendMessage(param,function(status,messageId){
     if(status==0){
         alert("准备发送 messageId: " + messageId);
     }else if(status==1){
         alert("发送成功 messageId: " + messageId);
     }else{
       alert("发送失败 messageId: " + messageId);
     }
  }); 

    或  

    var param = {
    objectName: "RC:TxtMsg",//发文字消息
    conversationType: "PRIVATE",
    targetId: "55666",
    extra: "extra info ...", 
    text: "text content ...", //消息的文字内容
  };
  uexRongCloud.sendMessage(param,function(status,messageId){
     if(status==0){
         alert("准备发送 messageId: " + messageId);
     }else if(status==1){
         alert("发送成功 messageId: " + messageId);
     }else{
       alert("发送失败 messageId: " + messageId);
     }
  });

onMessageReceived //发送消息的回调

uexRongCloud.onMessageReceived(result)

说明:

发送消息的回调。

参数:

var result = {
    message:
        {
            content: { //格式见:message -> content字段， 如：文字消息内容
                text: ,
                extra:
            }, 
            conversationType: , 
            messageDirection:, 
            targetId: ,
            objectName:, 
            sentStatus:, 
            senderUserId:, 
            messageId:, 
            sentTime:, 
            receivedTime: 
        },
        left:  
}

message -> content字段

    //objectName 为"RC:TxtMsg"时(文字消息)
    text:,//消息的文字内容
    extra:,//消息的附加字段

    //objectName 为"RC:VcMsg"时(语音消息) 
    voicePath:,//语音文件的路径  
    duration:,//Number类型 语音消息的时长,单位为秒
    extra:,//消息的附加字段


    //objectName 为"RC:ImgMsg"时(图片消息) 
    imgPath:,//图片的本地路径  
    thumbPath:,//缩略图
    extra:,//消息的附加字段

    //objectName 为"RC:ImgTextMsg"时(图文消息) 
    title:,//消息的标题
    description:,//消息的内容描述
    imgPath:,//图文消息图片URL
    url://图文消息中包含的需要跳转到的URL 
    extra:,//消息的附加字段

    //objectName 为"RC:LBSMsg"时(位置消息) 
    latitude:,//维度
    longitude:,//经度
    poi:,//地理位置的名称
    imgPath:,//地图略缩图的路径
    extra:,//消息的附加字段


    //objectName 为"RC:CmdNtf"时(命令消息) 
    name:,//命令的名称
    data:,//命令的数据

示例:

window.uexOnload = function() {
   uexRongCloud.onMessageReceived = onMessageReceived;
};
function onMessageReceived(info) {
  alert('onMessageReceived: ' + JSON.stringify(info));
}

2.4、会话功能

getConversationList //获取会话列表

var result = getConversationList();

说明:

获取会话列表,同步返回。

参数

无

返回值

返回值result为json字符串,各字段如下所示:

var result = {
    resultCode:,// Number  0 返回成功,其他为失败
    conversations:[
        {
            conversationTitle:, 
            conversationType:, 
            draft:, 
            targetId:, 
            latestMessage: { //objectName 为"RC:TxtMsg"时(文字消息)
                text:,
                extra:
            }, // 最后一条消息的内容，格式和onMessageReceived的message -> content字段相同
            sentStatus:, 
            objectName:, 
            receivedStatus: , 
            senderUserId:, 
            unreadMessageCount:, 
            receivedTime:, 
            sentTime:
            isTop:,  
            latestMessageId:
        }
        ....
    ]
}

示例:

var result = uexRongCloud.getConversationList();
  alert(result);

getConversation //获取某一会话信息

var result = uexRongCloud.getConversation(param);

说明:

获取某一会话信息,同步返回。

参数:

var param = {
     conversationType:,//消息的会话类型
     targetId:,//目标会话ID
}

返回值

var result = uexRongCloud.getConversation(param);

返回值result为json字符串,字段如下所示：

var result = {
    resultCode:,//Number, 0为返回成功,其他为失败
    conversationTitle:, // String，会话标题
    conversationType:, // String，会话类型
    draft:, // String，文字消息草稿的内容
    targetId:, // String，消息目标 Id
    latestMessage: {
    }, //JSON对象，消息的内容，格式和onMessageReceived的message -> content字段相同
    sentStatus:, //String, 发送状态:DESTROYED:对方已销毁 ;FAILED:发送失败; READ:对方已读; RECEIVED:对方已接收; SENDING:发送中; SENT:已发送;
    objectName:, // String，消息的类型, "RC:TxtMsg":文字消息;"RC:VcMsg":语音消息;"RC:ImgMsg":图片消息;"RC:ImgTextMsg":图文消息;"RC:LBSMsg":位置消息;"RC:CmdMsg":命令消息  
    recievedStatus: , //String，消息的接收状态,"UNREAD":未读；"READ":已读；"LISTENED":已听，仅用于语音消息;"DOWNLOADED":已下载
    senderUserId: , // String，消息的发送者用户ID
    unreadMessageCount: , //Number，本会话的未读消息数
    receivedTime: , //Number， 消息的接收时间,从1970年1月1日0点0分0秒开始到现在的毫秒数
    sentTime: , //Number， 消息的发送时间,从1970年1月1日0点0分0秒开始到现在的毫秒数
    isTop:, //bool，是否置顶，true为置顶，false为不置顶
    latestMessageId: // Number，消息ID
}

示例:

var params = {
    conversationType: "PRIVATE",
    targetId: "55666"
  };
  var data = JSON.stringify(params);
  var result = uexRongCloud.getConversation(data);
  alert(result);

removeConversation //从会话列表中移除某一会话

uexRongCloud.removeConversation(param,callback);

说明:

从会话列表中移除某一会话,但是不删除会话内的消息。

参数:

var params={
    conversationType:,//消息的会话类型
    targetId:,//消息目标 Id
}

回调参数

var callback=function(error,data){}

示例:

var param = {
    conversationType: "PRIVATE",
    targetId: "55666"
  };
  uexRongCloud.removeConversation(param,function(error, data){
     if(!error){
         alert("移除会话成功");
     }
  });

clearConversations //清空所有会话及会话消息

uexRongCloud.clearConversations(param,callback);

说明:

清空所有会话及会话消息。

参数:

var params={
    conversationTypes:
}

回调参数:

var callback = function (error,data){}

示例:

 var types = new Array();
 types[0] = "PRIVATE";
 var param = {
    conversationTypes: types
 };
 uexRongCloud.clearConversations(param,function(error, data){
     if(!error){
         alert("清空成功");
     }
 });

setConversationToTop //设置会话置顶

uexRongCloud.setConversationToTop(param,callback);

说明:

设置会话置顶。

参数:

var params={
    conversationType:,
    targetId:,
    isTop:
}

回调参数:

var callback = function(error,data){}

示例:

var param = {
    conversationType: "PRIVATE",
    targetId: "55666",
    isTop: true
  };
  uexRongCloud.setConversationToTop(param,function(error,data){
     if(!error){
         alert("置顶成功");
     }
  });

getConversationNotificationStatus //获取某一会话的通知状态

uexRongCloud.getConversationNotificationStatus(param,callback);

说明:

获取某一会话的通知状态。

参数

var param={
    conversationType:,
    targetId:
}

回调参数:

var callback=function (error,data){}

示例:

var param = {
    conversationType: "PRIVATE",
    targetId: "55666"
  };
  uexRongCloud.getConversationNotificationStatus(param,function (error, data) {
    if(!error){
       alert("获取某一会话的通知状态成功");
    }
});

setConversationNotificationStatus //设置某一会话的通知状态

uexRongCloud.setConversationNotificationStatus(param,callback);

说明:

设置某一会话的通知状态。

参数:

var param={
    conversationType:,
    targetId:,
    status:
}

回调参数:

var callback=function (error,data){}

示例:

var param = {
    conversationType: "PRIVATE",
    targetId: "55666",
    status: 1
  };
  uexRongCloud.setConversationNotificationStatus(param, function (error, data) {
  if(!error){
       alert("设置某一会话的通知状态成功");
    }

});

getLatestMessages //获取某一会话的最新消息记录

uexRongCloud.getLatestMessages(param,callback);

说明:

获取某一会话的最新消息记录。

参数:

var params={
    conversationType:,//消息的会话类型
    targetId:,//消息目标 Id
    count:,//Number 要获取的消息数量
}

回调参数:

var callback=function (error,data){}

data各字段如下：

var data = [
        {
            content: {
                text: ,
                extra: 
            }, // 消息内容,格式和onMessageReceived的message -> content字段相同
            extra:, // String，消息的附加信息,此信息只保存在本地
            conversationType:, //String，会话类型
            messageDirection:, //String 消息方向 发送:SEND  接收:RECEIVE
            targetId:, // String，这里对应消息发送者的 userId
            objectName:, //String， 消息类型 
            sentStatus:, // String, 发送状态:DESTROYED:对方已销毁 ;FAILED:发送失败; READ:对方已读; RECEIVED:对方已接收; SENDING:发送中; SENT:已发送;
            senderUserId:, // String，消息发送者 userId
            messageId:,// Number，消息 Id
            sentTime:,// Number，发送消息的时间戳,从1970年1月1日0点0分0秒开始到现在的毫秒数
            receivedTime: //Number， 收到消息的时间戳,从1970年1月1日0点0分0秒开始到现在的毫秒数
    }
    ...
]

示例:

var param = {
    conversationType: "PRIVATE",
    targetId: "55666",
    count: 20
  };
  uexRongCloud.getLatestMessages(param, function (error, data) {
    if(!error){
       alert(JSON.stringify(data));
    }
});

getHistoryMessages //获取某一会话的历史消息记录

uexRongCloud.getHistoryMessages(param,callback);

说明:

获取某一会话的历史消息记录。

参数:

var params={
    conversationType:,
    targetId:,
    count:,
    oldestMessageId:
}

回调参数:

var callback = function (error,data){}

data各字段如下：

var params=[
        {
            content: {
                text: ,
                extra: 
            }, // 消息内容,格式和onMessageReceived的message -> content字段相同
            extra:, // String,消息的附加信息,此信息只保存在本地
            conversationType:, //String,会话类型
            messageDirection:, //String, 消息方向 发送:SEND  接收:RECEIVE
            targetId:, //String, 这里对应消息发送者的 userId
            objectName:, //String, 消息类型 
            sentStatus:, //String, 发送状态:DESTROYED:对方已销毁 ;FAILED:发送失败; READ:对方已读; RECEIVED:对方已接收; SENDING:发送中; SENT:已发送;
            senderUserId:, // String,发送者 userId
            messageId:,//Number, 本地消息 Id
            sentTime:,// Number,发送消息的时间戳,从1970年1月1日0点0分0秒开始到现在的毫秒数
            receivedTime: //Number, 收到消息的时间戳,从1970年1月1日0点0分0秒开始到现在的毫秒数
        }
        ...
]

示例:

  var param = {
    conversationType: "PRIVATE",
    targetId: "55666",
    count: 2,
    oldestMessageId: 10
  };
  uexRongCloud.getHistoryMessages(param, function (error, data) {
     if(!error){
        alert(JSON.stringify(data));
     }
});

deleteMessages //删除消息

uexRongCloud.deleteMessages(param,callback);

说明:

删除消息。

参数:

var param = {
    messageIds:
}

回调参数:

var callback = function (error,data){}

示例:

  var ids = new Array();
  ids[0]= 12;
  var param = {
   messageIds: ids
  };
  uexRongCloud.deleteMessages(param, function (error, data) {
   if(!error){
      alert("删除成功");
   }
});

clearMessages //清空某一会话的所有聊天消息记录

uexRongCloud.clearMessages(param,callback);

说明:

清空某一会话的所有聊天消息记录。

参数:

var param = {
    conversationType:,
    targetId:
}

回调参数:

var callback = function (error,data){}

示例:

  var param = {
    conversationType: "PRIVATE",
    targetId: "55666"
  };
  uexRongCloud.clearMessages(param, function (error, data) {
     if(!error){
        alert("清空成功");
     }
});

getTotalUnreadCount //获取所有未读消息数

var count = uexRongCloud.getTotalUnreadCount();

说明:

获取所有未读消息数。

参数

无

返回值

示例:

var count = uexRongCloud.getTotalUnreadCount();
alert(count);

getUnreadCount //获取来自某用户(某会话)的未读消息数

var count = uexRongCloud.getUnreadCount(param);

说明:

获取来自某用户(某会话)的未读消息数。

参数:

var params={
    conversationType:,
    targetId:
}

返回值

示例:

var param = {
    conversationType:"PRIVATE",
    targetId:"55666"
  };
  var count = uexRongCloud.getUnreadCount(param);
  alert(count);

getUnreadCountByConversationTypes //获取某(些)会话类型的未读消息数

var count = uexRongCloud.getUnreadCountByConversationTypes(param);

说明:

获取某(些)会话类型的未读消息数。支持同步返回

参数:

var param ={
    conversationTypes:,//消息的会话类型,是conversationType的数组
}

返回值

示例:

  var types = new Array();
    types[0]= "PRIVATE";
    var param = {
    conversationTypes: types
    };
    var count = uexRongCloud.getUnreadCountByConversationTypes(param);
    alert(count);

setMessageReceivedStatus //设置接收到的消息状态

uexRongCloud.setMessageReceivedStatus(param);

说明:

设置接收到的消息状态。

参数:

var param = {
    messageId:,
    receivedStatus:
}

示例:

  var param = {
    messageId: 12, 
    receivedStatus: "READ"
  };
  uexRongCloud.setMessageReceivedStatus(param);

clearMessagesUnreadStatus //清除某一会话的消息未读状态

uexRongCloud.clearMessagesUnreadStatus(param);

说明:

清除某一会话的消息未读状态，iOS不支持

参数:

var param = {
    conversationType:,
    targetId:
}

示例:

  var param = {
    conversationType: "PRIVATE",
    targetId: "55666"
  };
  uexRongCloud.clearMessagesUnreadStatus(param);

3、附录

建立连接返回的错误码

具体业务错误码

4、更新历史

iOS

API版本:uexRongCloud-4.0.0

最近更新时间:2016-9-9

Android

API版本:uexRongCloud-4.0.0

最近更新时间:2016-9-9

5 文档更新记录