====== 在线状态订阅 Android ======
更新时间：2022-06-22
用户在线状态（即 Presence）包含用户的在线、离线以及自定义状态。
本文介绍如何在即时通讯应用中发布、订阅和查询用户的在线状态。
===== 技术原理 =====
环信 IM SDK 提供 ''%%EMPresence%%''、''%%EMPresenceManager%%'' 和 ''%%EMPresenceListener%%'' 类，用于管理在线状态订阅，包含如下核心方法：
* ''%%subscribePresences%%''：订阅用户的在线状态；
* ''%%publishPresence%%''：发布自定义在线状态；
* ''%%addListener%%''：添加在线状态监听器；
* ''%%onPresenceUpdated%%''：被订阅用户的在线状态变更时，订阅者收到监听回调；
* ''%%unsubscribePresences%%''：无需关注用户的在线状态时，取消订阅；
订阅用户在线状态的基本工作流程如下：
[[https://docs-im.easemob.com/_detail/ccim/android/2.9.2_presence_ios.png?id=ccim%3Aandroid%3Apresence|{{https://docs-im.easemob.com/_media/ccim/android/2.9.2_presence_ios.png?w=600&tok=ad8168|img}}]]
如上图所示，订阅用户在线状态的基本步骤如下：
1、用户 A 订阅用户 B 的在线状态； 2、用户 B 的在线状态发生变更； 3、用户 A 收到 ''%%onPresenceUpdated%%'' 回调。
效果如下图：
[[https://docs-im.easemob.com/_detail/ccim/ios/status.png?id=ccim%3Aandroid%3Apresence|{{https://docs-im.easemob.com/_media/ccim/ios/status.png|img}}]]
===== 前提条件 =====
使用在线状态功能前，请确保满足以下条件：
- 完成 ''%%3.9.1 以上版本%%'' SDK 初始化，详见 [[https://docs-im.easemob.com/ccim/android/quickstart|快速开始]]。
- 了解环信即时通讯 IM API 的[[https://docs-im.easemob.com/ccim/limitation|使用限制]]。
- 已联系商务开通在线状态订阅功能。
===== 实现方法 =====
本节介绍如何使用环信 IM SDK 提供的 API 实现上述功能。
==== 订阅指定用户的在线状态 ====
默认情况下，你不关注任何其他用户的在线状态。你可以通过调用 ''%%com.hyphenate.chat.EMPresenceManager#subscribePresences%%'' 方法订阅指定用户的在线状态，示例代码如下：
EMClient.getInstance().presenceManager().subscribePresences(contactsFromServer, 1 * 24 * 3600, new EMValueCallBack>() {
@Override
public void onSuccess(List presences) {
}
@Override
public void onError(int errorCode, String errorMsg) {
}
});
成功订阅指定用户的在线状态后，SDK 通过 ''%%onSuccess%%'' 回调返回被订阅用户的在线状态。
在线状态变更时，订阅者会收到 ''%%com.hyphenate.EMPresenceListener#onPresenceUpdated%%'' 回调。
**注意**
* 订阅时长最长为 30 天，过期需重新订阅。如果未过期的情况下重复订阅，新设置的有效期会覆盖之前的有效期。
* 每次调用接口最多只能订阅 100 个账号，若数量较大需多次调用。每个用户 ID 订阅的用户数不超过 3000。如果超过 3000，后续订阅也会成功，但默认会将订阅剩余时长较短的替代。
==== 发布自定义在线状态 ====
用户在线时，可调用 ''%%com.hyphenate.chat.EMPresenceManager#publishPresence%%'' 方法发布自定义在线状态：
EMClient.getInstance().presenceManager().publishPresence("自定义状态", new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String error) {
}
});
在线状态发布后，发布者和订阅者均会收到 ''%%com.hyphenate.EMPresenceListener#onPresenceUpdated%%'' 回调。
==== 添加在线状态监听器 ====
添加用户在线状态的监听器，示例代码如下：
EMClient.getInstance().presenceManager().addListener(new MyPresenceListener());
参考如下示例代码，使用 ''%%EMPresenceListener%%'' 监听器实现以下接口。当订阅的用户在线状态发生变化时，会收到''%%onPresenceUpdated%%'' 回调。
public interface EMPresenceListener {
void onPresenceUpdated(List presences);
}
==== 取消订阅指定用户的在线状态 ====
若取消指定用户的在线状态订阅，可调用 ''%%com.hyphenate.chat.EMPresenceManager#unsubscribePresences%%'' 方法，示例代码如下：
EMClient.getInstance().presenceManager().unsubscribePresences(contactsFromServer, new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int errorCode, String errorMsg) {
}
});
==== 查询被订阅用户列表 ====
为方便用户管理订阅关系，SDK 提供 ''%%com.hyphenate.chat.EMPresenceManager#fetchSubscribedMembers%%'' 方法，可使用户分页查询自己订阅的用户列表，示例代码如下：
EMClient.getInstance().presenceManager().fetchSubscribedMembers(1, 50, new EMValueCallBack>() {
@Override
public void onSuccess(List subscribedMembers) {
}
@Override
public void onError(int errorCode, String errorMsg) {
}
});
==== 获取用户的当前在线状态 ====
如果不关注用户的在线状态变更，你可以调用 ''%%com.hyphenate.chat.EMPresenceManager#fetchPresenceStatus%%'' 获取用户当前的在线状态，而无需订阅状态。示例代码如下：
EMClient.getInstance().presenceManager().fetchPresenceStatus(contactsFromServer, new EMValueCallBack>() {
@Override
public void onSuccess(List presences) {
}
@Override
public void onError(int errorCode, String errorMsg) {
}
});