Bmob im sdk开源
Switch branches/tags
Nothing to show
Clone or download
bodismile 更新旧版IM文档
更新旧版IM文档
Latest commit f764ba2 Mar 9, 2016

README.md

Bmob旧版即时通讯服务

注:官方已不再对其进行维护,使用上如有问题,可导入源码自行调试。

Bmob即时通讯服务包含了IM聊天所需要的所有核心功能:

  • 五种类型的消息任你发:纯文本、聊天表情、图片、位置、语音
  • 完善的用户管理功能:注册、登录
  • 完善的好友管理功能:添加好友、删除好友、获取好友列表、黑名单管理
  • 会话的本地化存储

同时,还增加了以下几大个性功能:

  • 支持陌生人聊天;
  • 新增LBS定位,允许查看附近的人;
  • 支持同一账号多处登陆强制下线;
  • 支持消息重发机制,由网络或者其他原因导致的消息发送失败皆可点击重发;
  • 支持消息回执发送:已发送、已阅读两种状态;
  • 支持自定义聊天消息,便于开发者扩展;
  • 新增定时检测服务,大幅度增加稳定性和及时性,保证百分百到达。

UI效果

Android注册页面

Android登录页面

Android会话页面

Android聊天页面

Android语音聊天页面

Android通讯录页面

Android黑名单页面

Android查找好友页面

Android新朋友页面

Android附近的人页面

Android个人资料页面

Android设置页面

快速入门

BmobIMSDK是在Bmob Android SDK(使用到云数据库、用户管理、文件管理等服务)、Bmob Push SD的基础上实现的,因此,想要在自己的应用中快速集成聊天功能,需要获取Bmob平台的Application ID。如果你还不知道怎么获取Application ID,你可以先快速浏览Android快速入门手册

请按照以下步骤完成IM的集成工作:

1、集成IMSDK

  1. 导入本Github地址内的BmobIM_V1.1.9的library源码工程或者直接下载Bmob_IM_V1.1.9_20150820.zip:其包含IMSDK、BmobSDK以及官方demo。
  2. 新建Android工程,将下载下来的官方demo工程中libs下面的BmobIMSDK和配套使用的BmobSDK一起复制到你新建工程的libs。

注:

1、官方demo的libs下面有很多的jar文件,如果你需要Bmob即时通讯服务提供的所有核心功能和个性功能,建议全部复制到新建工程的libs下面。当然百度地图这块,开发者可自行替换新版。

2、IMSDK内部集成了Bmob的PushSDK,故你想使用推送功能的话,不再需要导入Push SDK的包啦

2、填写包名

BmobIM内部集成了BmobPush服务的,所以需要在官网管理后台的消息推送->推送设置->应用包名中填写应用的正确包名。

3、 配置AndroidManifest.xml

  1. 添加permission:
    <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.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
    <permission
        android:name="cn.bmob.permission.push"
        android:protectionLevel="normal" >
    </permission>
    <uses-permission android:name="cn.bmob.permission.push" />   

注:以上只是和BmobIM有关的基础权限,官方demo中的AndroidManifest.xml文件中还有很多其他的权限,如果你需要Bmob即时通讯服务提供的所有核心功能和个性功能,建议全部复制

  1. 添加Service、receiver标签:
  <!-- IM聊天所需的Push start-->
    <service
        android:name="cn.bmob.push.lib.service.PushService"
        android:exported="true"
        android:label="PushService"
        android:permission="cn.bmob.permission.push"
        android:process="cn.bmob.push" >
        <intent-filter>
            <action android:name="cn.bmob.push.lib.service.PushService" />
        </intent-filter>
    </service>

    <receiver android:name="cn.bmob.push.PushReceiver" >
        <intent-filter android:priority="2147483647" > <!-- 优先级加最高 -->
            <!-- 系统启动完成后会调用 -->
            <action android:name="android.intent.action.BOOT_COMPLETED" />
            <!-- 解锁完成后会调用 -->
            <action android:name="android.intent.action.USER_PRESENT" />
            <!-- 监听网络连通性 -->
            <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
        </intent-filter>
    </receiver>
   <!--聊天消息接收器 -->
    <receiver android:name=".MyMessageReceiver" >
        <intent-filter>
            <action android:name="cn.bmob.push.action.MESSAGE" />
        </intent-filter>
    </receiver>

    <!-- IM聊天所需的Push end-->
    
    <!-- 个性功能中的启动定时检测服务,可选功能 -->
     <service android:name="cn.bmob.im.poll.BmobPollService">
        <intent-filter>
            <action android:name="cn.bmob.im.service.BmobPollService"/>
        </intent-filter>
    </service>

4、初始化

在应用的启动页的onCreate方法中完成初始化,可同步设置调试模式,方便开发者调试,正式发布时需注释。

	protected void onCreate(Bundle savedInstanceState) {
		//可设置调试模式,当为true的时候,会在logcat的BmobChat下输出一些日志,包括推送服务是否正常运行,如果服务端返回错误,也会一并打印出来。方便开发者调试,正式发布应注释此句。
		BmobChat.DEBUG_MODE = true;
		//BmobIM SDK初始化--只需要这一段代码即可完成初始化
		BmobChat.getInstance(this).init(Config.applicationId);
		//省略其他代码
	}

注:

  1. 初始化方法包含了BmobSDK的初始化步骤,故无需再初始化BmobSDK
  2. 详细代码请查看SplashActivity.java文件和Config.java

5、注册消息接收器

public class MyMessageReceiver extends BroadcastReceiver {

	// 事件监听
	public static ArrayList<EventListener> ehList = new ArrayList<EventListener>();

	@Override
	public void onReceive(Context context, Intent intent) {
		String json = intent.getStringExtra("msg");
		BmobLog.i("收到的message = " + json);
		//省略其他代码
	}
}

注:

** 1、MyMessageReceiver.java类中负责的是最重要的消息处理这块的功能,建议全部复制。**

** 2、如果你使用了IM SDK,又需要推送的功能,那么你无需修改任何东西,消息的发送可以参考推送文档。**

说明如下:

1、无须添加BmobPush的jar包,因为im内部已经集成了push服务;

2、无须添加push的初始化代码,因为im的初始化代码包含了Push服务的初始化操作。

核心功能

用户管理

注册

由于每个应用的注册所需的资料都不一样,故IM sdk未提供注册方法,用户可按照bmod SDK的注册方式进行注册。

但注册完的回调onSuccess方法中必须添加如下代码来完成设备与用户之间的绑定操作:

userManager.bindInstallationForRegister(bu.getUsername())

示例如下:

	final User bu = new User();
	bu.setUsername(name);
	bu.setPassword(password);
	//将user和设备id进行绑定aa
	bu.setSex(true);
	bu.setDeviceType("android");
	bu.setInstallId(BmobInstallation.getInstallationId(this));
	bu.signUp(RegisterActivity.this, new SaveListener() {

		@Override
		public void onSuccess() {
			// TODO Auto-generated method stub
			// 将设备与username进行绑定
			userManager.bindInstallationForRegister(bu.getUsername());
			//更新地理位置信息,如果需要LBS功能,建议添加此代码
			updateUserLocation();
			//省略其他代码
		}

		@Override
		public void onFailure(int arg0, String arg1) {
			// TODO Auto-generated method stub
			ShowToast("注册失败:" + arg1);
		}
	});

更多详细的代码请查看RegisterActivity.java文件。

登录
	User user = new User();
	user.setUsername(name);
	user.setPassword(password);
	userManager.login(user,new SaveListener() {

		@Override
		public void onSuccess() {
			// TODO Auto-generated method stub
			//更新用户的地理位置以及好友的资料,可自行到BaseActivity类中查看此方法的具体实现,建议添加
			updateUserInfos();
			//省略其他代码
		}

		@Override
		public void onFailure(int errorcode, String arg0) {
			// TODO Auto-generated method stub
			ShowToast(arg0);
		}
	});

更多详细的代码请查看LoginActivity.java文件。

退出登录
	/**
	 * 退出登录,清空缓存数据
	 */
	public void logout() {
		BmobUserManager.getInstance(getApplicationContext()).logout();
		setContactList(null);
		setLatitude(null);
		setLongtitude(null);
	}

更多详细的代码请查看CustomApplcation.java文件。

好友管理

获取好友列表
	userManager.queryCurrentContactList(new FindListener<BmobChatUser>() {
		@Override
		public void onError(int arg0, String arg1) {
			//省略其他代码
		}

		@SuppressWarnings("unchecked")
		@Override
		public void onSuccess(List<BmobChatUser> arg0) {
			// 保存到application中方便比较
			CustomApplcation.getInstance().setContactList(CollectionUtils.list2map(BmobDB.create(LoginActivity.this).getContactList()));
		}
	});

为了提升加载速度,获取到的好友列表都加载到本地数据库和内存中。更多详细的代码请查看LoginActivity.java文件。

添加好友
	//发送TAG_ADD_CONTACT请求
	BmobChatManager.getInstance(mContext).sendTagMessage(BmobConfig.TAG_ADD_CONTACT, contract.getObjectId(),new PushListener() {
		
		@Override
		public void onSuccess() {
			// TODO Auto-generated method stub
			progress.dismiss();
			ShowToast("发送请求成功,等待对方验证!");
		}
		
		@Override
		public void onFailure(int arg0, final String arg1) {
			// TODO Auto-generated method stub
			progress.dismiss();
			ShowToast("发送请求失败,请重新添加!");
		}
	});

更多详细的代码请查看AddFriendActivity.javaAddFriendAdapter.java文件。

删除好友
	userManager.deleteContact(user.getObjectId(), new UpdateListener() {
		
		@Override
		public void onSuccess() {
			// TODO Auto-generated method stub
			ShowToast("删除成功");
			//删除内存
			CustomApplcation.getInstance().getContactList().remove(user.getUsername());
			//省略其他
		}
		
		@Override
		public void onFailure(int arg0, String arg1) {
			// TODO Auto-generated method stub
			ShowToast("删除失败:"+arg1);
		}
	});

更多详细的代码请查看ContactFragment.java

查找某个好友
	userManager.queryUserByName(searchName, new FindListener<BmobChatUser>() {
		@Override
		public void onError(int arg0, String arg1) {
			ShowToast("用户不存在");
		}
				
		@Override
		public void onSuccess(List<BmobChatUser> arg0) {
			if(arg0!=null && arg0.size()>0){
				users.addAll(arg0);
				adapter.notifyDataSetChanged();
			}else{
				ShowToast("用户不存在");
			}
		}
	});

更多详细的代码请查看AddFriendActivity.java文件。

黑名单管理
1)、添加到黑名单
	// 添加到黑名单列表
	userManager.addBlack(username, new UpdateListener() {

		@Override
		public void onSuccess() {
			// TODO Auto-generated method stub
			ShowToast("黑名单添加成功!");
			//省略其他
		}

		@Override
		public void onFailure(int arg0, String arg1) {
			// TODO Auto-generated method stub
			ShowToast("黑名单添加失败:" + arg1);
		}
	});

更详细的代码请查看SetMyInfoActivity.java

2)、移出黑名单
	userManager.removeBlack(user.getUsername(),new UpdateListener() {
					
		@Override
		public void onSuccess() {
			// TODO Auto-generated method stub
			ShowToast("移出黑名单成功");
			//重新设置下内存中保存的好友列表
			CustomApplcation.getInstance().setContactList(CollectionUtils.list2map(BmobDB.create(getApplicationContext()).getContactList()));	
		}
		
		@Override
		public void onFailure(int arg0, String arg1) {
			// TODO Auto-generated method stub
			ShowToast("移出黑名单失败:"+arg1);
		}
	});

更详细的代码请查看BlackListActivity.java

消息发送

发送纯文本和聊天表情
	// 组装BmobMessage对象
	BmobMsg message = BmobMsg.createTextSendMsg(this, targetId, msg);
	//不带监听回调,默认发送完成,将数据保存到本地消息表和最近会话表中
	manager.sendTextMessage(targetUser, message);
   //带监听回调
   //sendTextMessage(BmobChatUser targetUser,BmobMsg msg, PushListener pushcallback)

发送图片
	manager.sendImageMessage(targetUser, local, new UploadListener() {

		@Override
		public void onStart(BmobMsg msg) {
			// TODO Auto-generated method stub
			ShowLog("开始上传onStart:" + msg.getContent() + ",状态:"
					+ msg.getStatus());
			refreshMessage(msg);
		}

		@Override
		public void onSuccess() {
			// TODO Auto-generated method stub
			mAdapter.notifyDataSetChanged();
		}

		@Override
		public void onFailure(int error, String arg1) {
			// TODO Auto-generated method stub
			ShowLog("上传失败 -->arg1:" + arg1);
			mAdapter.notifyDataSetChanged();
		}
	});

发送地理位置
	// 组装BmobMessage对象
	BmobMsg message = BmobMsg.createLocationSendMsg(this, targetId,
			address, latitude, longtitude);
	// 默认发送完成,将数据保存到本地消息表和最近会话表中
	manager.sendTextMessage(targetUser, message);

发送语音
	manager.sendVoiceMessage(targetUser, local, length,new UploadListener() {
	
			@Override
			public void onStart(BmobMsg msg) {
				// TODO Auto-generated method stub
				refreshMessage(msg);
			}
	
			@Override
			public void onSuccess() {
				// TODO Auto-generated method stub
				mAdapter.notifyDataSetChanged();
			}
	
			@Override
			public void onFailure(int error, String arg1) {
				// TODO Auto-generated method stub
				ShowLog("上传语音失败 -->arg1:" + arg1);
				mAdapter.notifyDataSetChanged();
			}
		});

注:BmobMsg类是消息发送和接收时的结构组装类,真正的发送还是通过BmobChatManager类来实现的。

五种类型消息发送的详细代码请查看ChatActivity.java文件。

删除本地聊天记录
/**删除与指定聊天对象之间的所有消息 
  * @Title: deleteMessages
  * @param  targetObjectId 当前聊天的objectid
  * @return 
  * @throws
  */
BmobDB.create(getActivity()).deleteMessages(String targetObjectId)

会话列表

查询全部会话
	BmobDB.create(getActivity()).queryRecents();
删除会话
	//此方法是删除本地会话表中与指定用户之间的会话消息
	BmobDB.create(getActivity()).deleteRecent(String targetObjectId);
	//此方法是删除聊天记录表中的与指定用户之间的聊天记录
	BmobDB.create(getActivity()).deleteMessages(String targetObjectId);

会话列表同样是存储在本地数据库中的,可以直接获取,更多详细代码请查看RecentFragment.java文件。

个性功能

支持陌生人聊天

SDK内部已经支持陌生人聊天了,聊天消息不再局限于好友关系,所以你只需要调用发送消息(上述的五种类型的消息)的方法就行。

查看附近的人

SDK内部提供了两个查询附近的人的方法,支持下拉刷新,具体方法如下:

查询指定范围指定性别的用户列表,允许是否显示自己的好友,默认不显示
	//封装的查询方法,当进入此页面时 isUpdate为false,当下拉刷新的时候设置为true就行。
	//此方法默认每页查询10条数据,若想查询多于10条,可在查询之前设置BRequest.QUERY_LIMIT_COUNT,如:BRequest.QUERY_LIMIT_COUNT=20
	//如果你不想查询性别为女的用户,可以将equalProperty设为null或者equalObj设为null即可
	userManager.queryKiloMetersListByPage(isUpdate,0,"location", longtitude, latitude, true,QUERY_KILOMETERS,"sex",false,new FindListener<User>() {

		@Override
		public void onSuccess(List<User> arg0) {
			// TODO Auto-generated method stub
			//省略其他
		}
		
		@Override
		public void onError(int arg0, String arg1) {
			// TODO Auto-generated method stub
			ShowToast("暂无附近的人!");
		}

	});
查询所有带地理位置信息的人,不限制地理范围,可指定性别,允许是否显示自己的好友,默认不显示
userManager.queryNearByListByPage(isUpdate,0,"location", longtitude, latitude, true,"sex",false,new FindListener<User>() {
		@Override
		public void onSuccess(List<User> arg0) {
			// TODO Auto-generated method stub
			//省略其他
		}
		
		@Override
		public void onError(int arg0, String arg1) {
			// TODO Auto-generated method stub
			ShowToast("暂无附近的人!");
		}

	});

更多详细代码请查看NearPeopleActivity.java文件

支持消息重发机制

重发文本
BmobChatManager.getInstance(ChatActivity.this).resendTextMessage(targetUser, (BmobMsg) values, new PushListener);
重发图片和语音
BmobChatManager.getInstance(ChatActivity.this).resendFileMessage(targetUser, (BmobMsg) values, new UploadListener);

更多详细代码请查看ChatActivity.java文件

聊天消息允许增加额外字段

如果开发者希望能够增加一些发送过去的消息字段,比如,想加个性别,可根据消息类型使用如下方法发送消息:

如果是发送文本,比较特殊:

BmobMsg message = BmobMsg.createTextSendMsg(this, targetId, msg);
message.setExtra("Bmob");
manager.sendTextMessage(targetUser, message);

如果是发送图片,可调用:

sendImageMessage(final BmobChatUser targetUser,final String localPath,String extra, final UploadListener uploadCallback)

如果是发送语音,可调用:

sendVoiceMessage(BmobChatUser targetUser,String localPath, int length,	String extra,final UploadListener uploadCallback)

允许自定义聊天消息

如果上述这些都不满足你的需求,那么你可以使用:

//带监听回调
sendJsonMessage(String json,String targetId,PushListener pushCallback)
//不带监听回调
sendJsonMessage(String json,final String targetId)

注:此方法用于扩展MsgTag,发送自定义格式的消息,这个格式可以随便定义,只负责发送消息,不提供自定义格式的消息的处理,需要开发者自己处理逻辑,比如消息存储等。

允许自定义通知栏提示语

当收到聊天消息的时候,通知栏默认会显示XXX(用户名)发来了一个(消息/图片/语音/位置),如果开发者想要定制自己的通知栏提示语,可以根据消息类型使用如下方法发送消息:

如果是发送文本消息,有两个方法可供选择:

//不带监听回调
sendTextMessage(BmobChatUser targetUser,BmobMsg msg, String showAlert)

//带监听回调
sendTextMessage(BmobChatUser targetUser,BmobMsg msg, String showAlert,PushListener pushcallback);

如果是发送图片,可调用:

sendImageMessage(BmobChatUser targetUser,String localPath,String extra, String showAlert,UploadListener uploadCallback)

如果是发送语音,可调用:

sendVoiceMessage(BmobChatUser targetUser,String localPath, int length,	String extra,String showAlert,UploadListener uploadCallback)

注:如果你不想填写showAlert的话,可传""或者null值。

新增定时检测服务

由于受网络和推送服务器的影响,有可能导致聊天消息丢失,用户无法接收到聊天消息,而IM聊天不允许出现聊天消息丢失的情况,故在sdk内部增加了定时检测服务,将未接收到的未读消息再次返回给用户。

开启服务

建议在应用的启动页开启检测服务

	//开启定时检测服务(单位为秒)-在这里检测后台是否还有未读的消息,有的话就取出来
	//如果你觉得检测服务比较耗流量和电量,你也可以去掉这句话-同时还有onDestory方法里面的stopPollService方法
	//BmobChat.getInstance(this).startPollService(30);
停止服务
	//取消定时检测服务
	//BmobChat.getInstance(this).stopPollService();
注册接收广播

开启检测服务后,需要在合适的地方注册下面两类广播并完成相应的页面逻辑处理。

注册聊天消息(文本、语音等)的接收广播
	private void initNewMessageBroadCast(){
		// 注册聊天消息的接收广播
		NewBroadcastReceiver newReceiver = new NewBroadcastReceiver();
		IntentFilter intentFilter = new IntentFilter(BmobConfig.BROADCAST_NEW_MESSAGE);
		//优先级要低于ChatActivity
		intentFilter.setPriority(3);
		registerReceiver(newReceiver, intentFilter);
	}
注册Tag消息(添加好友、下线等)的接收广播:
	private void initTagMessageBroadCast(){
		// 注册Tag消息的接收消息广播
	    TagBroadcastReceiver	userReceiver = new TagBroadcastReceiver();
		IntentFilter intentFilter = new IntentFilter(BmobConfig.BROADCAST_ADD_USER_MESSAGE);
		//优先级要低于ChatActivity
		intentFilter.setPriority(3);
		registerReceiver(userReceiver, intentFilter);
	}

更多详细代码请查看MainActivity.javaChatActivity.java文件

常见问题解答

为什么接收不到消息?

  • 是否已填写包名,因为BmobIM是基于BmobPush服务的,所以需要在官网管理后台的消息推送->推送设置->应用包名中填写应用的正确包名;
  • 是否是两台真机测试
    1. 模拟器或平板电脑未经过测试,故无法保证其能无法正常接收到消息。
    2. 很多人由于没有两部真机,会采用一个手机注册两个不同的账号,这样来回切换账户来测试聊天,这种方式达不到测试的效果,虽然这一版本的改进使得这种方式能够收到消息,但是及时性比较低。而之前的版本,这种方式是收不到消息的,故不建议这样测试,只有两部真机才能达到真实的聊天效果。
  • 是否安装低版本Push SDK,因为此IM是基于Bmob推送服务的,而sdk的demo里面也有演示推送服务的例子,但demo里面的BmobPush的sdk版本与IM里面的推送版本不一样,所以,如果安装的话,会影响到Im的消息接收,请卸载后重试;
  • 是否使用的是Android 5.0系统的手机,在Android 5.0的手机上会出现这样的错误:Service Intent must be explicit,最新版本V1.1.8已解决这个问题,可自行下载替换新版SDK。

为什么导入到Eclipse报错?

  • 工程所用的编码格式是GBK,所以大家导入到eclipse的时候需要自行修改下编码方式;
  • 有很多人导入了工程后发现有这个错:java.lang.IncompatibleClassChangeError: cn.bmob.im.project,这个是因为BmobIM_V1.1.5是基于BmobSDK_v3.2.8_0105混淆打包的,所以如果你要用的话,这两个包应该是一起导进去的,替换之前的Bmobsdk和BmobIM包。也就是说你不能随便将任意版本的BmobSDK导进来,你能导入的只能是和IMSDK一起发布出去的BmobSDK。

为什么无法发送地理位置信息?

请到百度地图官网申请key。因为demo中的定位以及地理位置用的都是百度的产品,所以需要开发者自行去百度地图官网重新申请map key,然后到AndroidManifest.xml中填写:

    <meta-data
        android:name="com.baidu.lbsapi.API_KEY"
        android:value="百度地图key" />

Bmob官方信息

官方网址:http://www.bmob.cn

问答社区:http://wenda.bmob.cn

技术邮箱:support@bmob.cn