目录
适用平台
适用于任何Java平台,包括但不限于安卓/Java服务器/Java桌面等
添加依赖包
在项目中添加sdk目录中最新的jar包:
即时消息:mimc-java-sdk-0.0.19-SNAPSHOT.jar
含实实时流:mimc-java-sdk-0.0.19-SNAPSHOT.jar + librts.so + libxmdtransceiver.so
安卓配置
// 权限
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
日志
打印到控制台
// 默认控制台不打印日志,若需要打印到控制台,实现如下接口:
MIMCLog.setLogger(new Logger() {
@Override
public void d(String tag, String msg) {
}
@Override
public void d(String tag, String msg, Throwable th) {
}
@Override
public void i(String tag, String msg) {
}
@Override
public void i(String tag, String msg, Throwable th) {
}
@Override
public void w(String tag, String msg) {
}
@Override
public void w(String tag, String msg, Throwable th) {
}
@Override
public void e(String tag, String msg) {
}
@Override
public void e(String tag, String msg, Throwable th) {
}
});
/**
* 设置控制台打印日志级别,默认INFO级别
* @param[level]:
* MIMCLog.DEBUG
* MIMCLog.INFO(默认)
* MIMCLog.WARN
* MIMCLog.ERROR
* MIMCLog.NONE(不启用)
*/
MIMCLog.setLogPrintLevel(int level);
/**
* 获取堆栈异常信息
*/
MIMCLog.getStackTraceString(Throwable th);
写到本地文件
/**
* 是否启用本地写日志文件功能,默认启用,INFO级别,日志文件所在位置是在调用MIMCUser.newInstance()时,传入的cachePath处
* @param[level]:
* MIMCLog.DEBUG
* MIMCLog.INFO(默认)
* MIMCLog.WARN
* MIMCLog.ERROR
* MIMCLog.NONE(不启用)
*/
MIMCLog.setLogSaveLevel(int level);
用户登录
用户初始化
/**
* @param[appId]: 应用ID,小米开放平台申请分配
* @param[appAccount]: 用户在APP账号系统内的唯一账号ID
* @param[resource]: 用户设备的标识
* 如不指定resource,SDK自动生成并支持多设备登录
* 如开发者指定resource,则需支持多设备登录:
* 同一台设备,resource要保持不变
* 不同设备,resource要相互不同
* @param[logCachePath]: 必须传入合法的路径,用于缓存日志信息
* @param[tokenCachePath]: 必须传入合法的路径,用于缓存token信息
*/
User user = MIMCUser.newInstance(long appId, String appAccount, String logCachePath, String tokenCachePath);
User user = MIMCUser.newInstance(long appId, String appAccount, String resource, String logCachePath, String tokenCachePath);
user.registerTokenFetcher(MIMCTokenFetcher tokenFetcher);
user.registerOnlineStatusListener(MIMCOnlineStatusListener onlineStatusListener);
user.registerMessageHandler(MIMCMessageHandler messageHandler);
//user.registerUnlimitedGroupHandler(MIMCUnlimitedGroupHandler unlimitedGroupHandler); // 无限大群回调注册
安全认证
参考 安全认证
interface MIMCTokenFetcher{
/**
* 同步访问代理认证服务(appProxyService)
* 从代理认证服务返回结果中获取[小米认证服务下发的原始数据]并返回
*/
public String fetchToken();
}
登录
/**
* 进程整个生命周期内login()调用一次即可
*/
user.login();
单点登录
/**
* @param[enableSSO]: 默认false,ture时打开启用标志,且实例化User对象时,传入相同resource时方可正式生效
* 注意:
* 必须在调用login()之前调用
* 当用户登录时,先前登录用户会收到下线回调,回调参数type = reason = desc = "single-resource-kick"
*/
user.enableSSO(boolean enableSSO);
在线状态变化回调
interface MIMCOnlineStatusHandler {
/**
* @param[status]: 登录状态,ONLINE 在线,OFFLINE 离线
* @param[type]: 状态变化类型
* @param[reason]: 状态变化原因
* @param[desc]: 状态变化描述信息
*/
public void statusChange(MIMCConstant.OnlineStatus status, String type, String reason, String desc);
}
登出
user.logout();
销毁
/**
* 切换用户时,将老用户destroy掉,然后为新用户newInstance()创建实例
*/
user.destroy();
发送消息
发送单聊消息
/**
* @param[toAppAccount]: 消息接收方在APP账号系统内的唯一账号ID
* @param[payload]: 开发者自定义消息体,最大不超过15KB
* @param[isStore]: 消息是否存储在mimc服务端,true 存储, false 不存储, 默认存储
* @param[bizType]: 消息类型,默认空字符串
* @param[isConversation]: 是否发送会话消息,默认false
* @return 客户端生成的消息ID,返回null说明消息未进入发送队列
*/
String packetId = user.sendMessage(String toAppAccount, byte[] payload);
String packetId = user.sendMessage(String toAppAccount, byte[] payload, boolean isStore);
String packetId = user.sendMessage(String toAppAccount, byte[] payload, boolean isStore, boolean isConversation);
String packetId = user.sendMessage(String toAppAccount, byte[] payload, String bizType);
String packetId = user.sendMessage(String toAppAccount, byte[] payload, String bizType, boolean isStore);
String packetId = user.sendMessage(String toAppAccount, byte[] payload, String bizType, boolean isStore, boolean isConversation);
发送群聊消息
/**
* @param[topicId]: 群ID
* @param[payload]: 开发者自定义消息体,最大不超过15KB
* @param[isStore]: 消息是否存储在mimc服务端,true 存储, false 不存储, 默认存储
* @param[bizType]: 消息类型,默认空字符串。
* @param[isConversation]: 是否发送会话消息,默认false
* @return 客户端生成的消息ID,返回null说明消息未进入发送队列
*/
String packetId = user.sendGroupMessage(long topicId, byte[] payload);
String packetId = user.sendGroupMessage(long topicId, byte[] payload, boolean isStore);
String packetId = user.sendGroupMessage(long topicId, byte[] payload, boolean isStore, boolean isConversation);
String packetId = user.sendGroupMessage(long topicId, byte[] payload, String bizType);
String packetId = user.sendGroupMessage(long topicId, byte[] payload, String bizType, boolean isStore);
String packetId = user.sendGroupMessage(long topicId, byte[] payload, String bizType, boolean isStore, boolean isConversation);
发送无限大群消息
/**
* @param[topicId]: 群ID
* @param[payload]: 开发者自定义消息体,最大不超过15KB
* @param[isStore]: 消息是否存储在mimc服务端,true 存储, false 不存储, 默认存储
* @param[bizType]: 消息类型,默认空字符串
* @return 客户端生成的消息ID
*/
String packetId = user.sendUnlimitedGroupMessage(long topicId, byte[] payload);
String packetId = user.sendUnlimitedGroupMessage(long topicId, byte[] payload, boolean isStore);
String packetId = user.sendUnlimitedGroupMessage(long topicId, byte[] payload, String bizType);
String packetId = user.sendUnlimitedGroupMessage(long topicId, byte[] payload, String bizType, boolean isStore);
发送在线消息
/**
* @param[toAppAccount]: 消息接收方在APP账号系统内的唯一账号ID
* @param[payload]: 开发者自定义消息体,最大不超过15KB
* @param[bizType]: 消息类型,默认空字符串
* @return 客户端生成的消息ID,返回null说明消息未进入发送队列
*/
String packetId = user.sendOnlineMessage(String toAppAccount, byte[] payload);
String packetId = user.sendOnlineMessage(String toAppAccount, byte[] payload, String bizType);
接收消息
interface MIMCMessageHandler {
/**
* @param[MIMCMessage]: 单聊消息
* MIMCMessage.packetId: 消息ID
* MIMCMessage.sequence: 服务器为消息分配的递增ID,可用于去重/排序
* MIMCMessage.timestamp: 发送时间戳
* MIMCMessage.fromAccount: 发送方账号
* MIMCMessage.fromResource: 发送方设备标识
* MIMCMessage.toAccount: 接收方账号
* MIMCMessage.toResource: 接收方设备标识
* MIMCMessage.payload: 消息体
* MIMCMessage.bizType: 消息类型
* MIMCMessage.convIndex: 会话索引,默认0值,说明没有启用会话消息,该字段由服务器填充,在一个会话中连续自增,从1开始
* @return 返回true说明消息被成功递交给应用层,若返回false说明消息递交失败,会再次触发该回调,直到返回true为止
*/
public boolean handleMessage(List<MIMCMessage> packets);
/**
* @param[MIMCGroupMessage]: 群聊消息
* MIMCGroupMessage.packetId: 消息ID
* MIMCGroupMessage.sequence: 服务器为消息分配的递增ID,可用于去重/排序
* MIMCGroupMessage.timestamp: 发送时间戳
* MIMCGroupMessage.fromAccount: 发送方账号
* MIMCGroupMessage.fromResource: 发送方设备标识
* MIMCGroupMessage.topicId: 群ID
* MIMCGroupMessage.payload: 消息体
* MIMCGroupMessage.bizType: 消息类型
* MIMCGroupMessage.convIndex: 会话索引,默认0值,说明没有启用会话消息,该字段由服务器填充,在一个会话中连续自增,从1开始
* @return 返回true说明消息被成功递交给应用层,若返回false说明消息递交失败,会再次触发该回调,直到返回true为止
*/
public boolean handleGroupMessage(List<MIMCGroupMessage> packets);
public boolean handleUnlimitedGroupMessage(List<MIMCGroupMessage> packets);
/**
* @param[serverAck]: 服务器返回的serverAck对象
* serverAck.packetId: 客户端生成的消息ID
* serverAck.timestamp: 消息发送到服务器的时间(单位:ms)
* serverAck.sequence: 服务器为消息分配的递增ID,可用于去重/排序
* serverAck.code: 服务器的返回码
* MSG_CHECK_ACCEPT返回100
* BLACKLIST_REFUSAL返回101
* MSG_CHECK_SENDER_NOT_IN_TOPIC返回102
* RUBBISH_MSG_REFUSAL返回103
* P2P_MESSAGE_EXCEED_MAX_QPS返回104
* TOPIC_BLACKLIST_REFUSAL返回105
* P2T_MESSAGE_EXCEED_MAX_QPS返回106
* TOPIC_ID_NOT_EXIST返回202
* NOT_IN_GROUP返回203
* MESSAGE_EXCEED_MAX_QPS返回204
* FORBID_SNED_UC_MESSAGE返回403
* serverAck.desc: 服务器返回的描述信息:
* MSG_CHECK_ACCEPT:表示消息被服务端正常接收
* BLACKLIST_REFUSAL:表示发送者在黑名单中
* MSG_CHECK_SENDER_NOT_IN_TOPIC:表示发送者不在群列表中
* RUBBISH_MSG_REFUSAL:表示发送的消息中含有垃圾消息(目前垃圾消息功能没有开启)
* P2P_MESSAGE_EXCEED_MAX_QPS:表示发送的消息超过qps限制
* TOPIC_BLACKLIST_REFUSAL:表示向群里发送消息的人被群禁言了
* P2T_MESSAGE_EXCEED_MAX_QPS字段:表示发送群聊的消息超过qps限制。
* TOPIC_ID_NOT_EXIST字段:表示群不存在。
* NOT_IN_GROUP字段:表示用户不在群内。
* MESSAGE_EXCEED_MAX_QPS:表示发送无限大群的消息超过qps限制。
* FORBID_SNED_UC_MESSAGE:群用户被禁言
* serverAck.convIndex: 会话索引,默认0值,说明没有启用会话消息,该字段由服务器填充,在一个会话中连续自增,从1开始
*/
public void handleServerAck(MIMCServerAck serverAck);
public void handleSendMessageTimeout(MIMCMessage message);
public void handleSendGroupMessageTimeout(MIMCGroupMessage groupMessage);
public void handleSendUnlimitedGroupMessageTimeout(MIMCGroupMessage groupMessage);
/**
* 通知主动拉取离线消息,拉取区间:(minSequence, maxSequence]
* 默认情况,当用户处于离线状态时,最多保留近7天内的离线消息,直到用户上线,持续下发缓存的离线消息。
* 若积压的离线消息过多,会一直下发离线消息,从而导致长时间无法接收最新消息,直到离线消息接收完毕为止。
* 我们支持设置一个阈值来控制离线消息是否持续下发,比如阈值设置为offlineMsgMaxCount=500,表示当离线消息达到500条时,触发onPullNotification(...)
* 回调,当回调接口返回true时,服务端会跳过离线消息,直接下发最新的实时消息,应用方可根据回调形参单独去拉取离线消息。
* 1)首先拉取会话列表;
* 2)然后用会话列表中的"sequence"字段和回调接口的“minSequence”形参进行比对,当sequence > minSequence时,说明需要拉取该会话的历史消息;
* 3)最后拉取历史消息,其中"fromAccount"字段从会话列表中提取即可。
* 会话列表:https://admin.mimc.chat.xiaomi.net/docs/13-chatlist.html
* 历史消息:https://admin.mimc.chat.xiaomi.net/docs/11-history.html
*/
boolean onPullNotification(long minSequence, long maxSequence);
void handleOnlineMessage(MIMCMessage onlineMessage);
/**
* @param[onlineMessageAck]: 服务器返回的onlineMessageAck对象,即发送在线消息对应的反馈信息
* onlineMessageAck.packetId: 客户端生成的消息ID
* onlineMessageAck.code: 服务器的返回码
* OFFLINE返回0
* RECEIVED返回1
* TIMEOUT返回2
* onlineMessageAck.desc: 服务器返回的描述信息:
* OFFLINE字段:接收方离线
* RECEIVED字段:接收方成功接收
* TIMEOUT字段:发送超时,默认10s
*/
void handleOnlineMessageAck(MIMCOnlineMessageAck onlineMessageAck);
}
无限大群
创建无限大群
/**
* @param[topicName]: 群名
* @param[context]: 用户自定义传入的对象,通过回调函数原样传出
*/
user.createUnlimitedGroup(String topicName, Object context);
加入无限大群
/**
* @param[topicId]: 群ID
* @param[context]: 用户自定义传入的对象,通过回调函数原样传出
* @return 客户端生成的消息ID
*/
String packetId = user.joinUnlimitedGroup(long topicId, Object context);
退出无限大群
/**
* @param[topicId]: 群ID
* @param[context]: 用户自定义传入的对象,通过回调函数原样传出
* @return 客户端生成的消息ID
*/
String packetId = user.quitUnlimitedGroup(long topicId, Object context);
解散无限大群
/**
* @param[topicId]: 群ID
* @param[context]: 用户自定义传入的对象,通过回调函数原样传出
*/
user.dismissUnlimitedGroup(long topicId, Object context);
无限大群回调
interface MIMCUnlimitedGroupHandler {
/**
* @param[topicId]: 群ID
* @param[topicName]: 群名
* @param[code]: 0成功,非0失败
* @param[desc]: 描述信息
* @param[context]: 用户自定义传入的对象
*/
void handleCreateUnlimitedGroup(long topicId, String topicName, int code, String desc, Object context);
/**
* @param[topicId]: 群ID
* @param[code]: 0成功,非0失败
* @param[desc]: 描述信息
* @param[context]: 用户自定义传入的对象
*/
void handleJoinUnlimitedGroup(long topicId, int code, String desc, Object context);
/**
* @param[topicId]: 群ID
* @param[code]: 0成功,非0失败
* @param[desc]: 描述信息
* @param[context]: 用户自定义传入的对象
*/
void handleQuitUnlimitedGroup(long topicId, int code, String desc, Object context);
/**
* 解散无限大群回调
* @param[topicId]: 群ID
* @param[code]: 0成功,非0失败
* @param[desc]: 描述信息
* @param[context]: 用户自定义传入的对象
*/
void handleDismissUnlimitedGroup(long topicId, int code, String desc, Object context);
/**
* 通知无限大群成员群解散回调
* @param[topicId]: 群ID
*/
void handleDismissUnlimitedGroup(long topicId);
}