Online Status Subscription
Update time: 2021/12/03 07:12:00
Overview
Users may implement the design mode programming method of "Publish-Subscribe" by publishing and subscribing events. This can be used to subscribe to the online status of specified users, users' personalized information.
At present, only the "type = 1" event subscription is available. Users may define the value (a value corresponds to the status of an event; 1-9999 is the value pre-defined by CommsEase, which the developer cannot use) as required for their business.
Rough process: A subscribes B ——> B publishes a specific event ——> A monitors any change in the event status from B ——> handle it based on the business logic analysis.
Note: it is not required to actively publish the online status event (type=1, value=1/2/3) in CommsEase system. The work will be hosted to CommsEase server.
Subscribing to events
Specific events are subscribed by specific users. It is required to subscribe built-in online status event or custom event using the interface. The maximum number of effective subscription accounts cannot exceed 3000. We recommend keeping consistent subscription duration at each client by the developer, because multi-client subscription (subscription of the same account in other types of client) will cover the validity period of subscription. In addition, it is noted that target event is not published for the same event subscription in the same account within 30 seconds in consideration of performance, even it is set as "immediate synchronization service".
- API prototype
java/**
* Subscription events.
*
* @param request - Information of subscription request. The event type, account of event publisher and period of validity of subscription must be filled in.
* @return InvocationFuture - Configurable callback feature. It will be invoked only after request. The set of accounts with failed subscription will be returned. If the array length is 0, all are successful. If an error occurs, detailed error code will be returned.
*/
InvocationFuture<List<String>> subscribeEvent(EventSubscribeRequest request);
- Parameters
EventSubscribeRequest
attribute
Parameter | Description |
---|---|
eventType | Event type. Only 1 is input. |
expiry | Validity period of subscription, ranging from 60 seconds to 30 days. Unit: seconds. |
syncCurrentValue | Determine that event state value is synchronized immediately after subscription. It is "false" by default. |
publishers | Account set of event publisher. |
For subscription events, fields like eventType
, expiry
, publishers
must be filled in a subscription request.
- Example
javaNIMClient.getService(EventSubscribeService.class).subscribeEvent(eventSubscribeRequest).setCallback(new RequestCallbackWrapper<List<String>>() {
@Override
public void onResult(int code, List<String> result, Throwable exception) {
if (code == ResponseCode.RES_SUCCESS) {
if (result != null) {
// Some accounts with failed subscription.
//
//
}
} else {
}
}
});
Unsubscribing from events
Unsubscribing from events by accounts
Users can unsubscribe from any specified type of event for a specified account. Fields eventType
and publishers
are required in the subscription request.
- API prototype
java/**
* Cancel subscription relationship of specified event by account.
*
* @param request - Cancel subscription. Only the event type and the set of accounts of event publishers (set of publishers) must be filled in.
* @return InvocationFuture - Configurable callback features. It will be invoked only after request. The set of accounts with failed operation in canceling subscription will be returned. If the array length is 0, all are successful. If an error occurs, detailed error codes will be returned.
*/
InvocationFuture<List<String>> unSubscribeEvent(EventSubscribeRequest request);
- Example
javaNIMClient.getService(EventSubscribeService.class).unSubscribeEvent(eventSubscribeRequest);
Unsubscribing from events by events
Unsubscribe from specified events.
- API prototype
java/**
* Cancel all subscriptions of specified events.
*
* @param request - Cancel subscription. Only the event type must be filled in.
* @return InvocationFuture - Configurable callback feature. It can be invoked only after request. If an error occurs, detailed error code will be returned.
*/
InvocationFuture<Void> batchUnSubscribeEvent(EventSubscribeRequest request);
- Example
javaNIMClient.getService(EventSubscribeService.class).batchUnSubscribeEvent(request);
Publishing events
Publish an event to subscribers. If built-in online status of CommsEase system cannot accommodate application demands or the developer requires some independent custom events, event can be published using the interface.
- API prototype
java/**
* Publish an event.
*
* @param event - Event
* @return InvocationFuture - Configurable callback feature. It can be invoked only after request. If an error occurs, detailed error codes will be returned.
*/
InvocationFuture<Event> publishEvent(Event event);
When event is published, Event
object must be created independently and required fields include:
eventType
: Input 1.eventValue
: value is 10000 and above (1-9999 are the values pre-defined by CommsEase and cannot be used by developers).
Event interfaces:
Return | Event interface | Description |
---|---|---|
void | setEventType(int eventType) | Set event type for publishing event. |
void | setEventValue(int eventValue) | Set event value for publishing event. |
void | setConfig(String config) | Set extension field of event. It is configured when an event is published at client. |
void | setBroadcastOnlineOnly(boolean only) | Broadcast to online subscribers only after event publication. |
void | setExpiry(long expiry) | Set validity period of event. Unit: second. Range: 60 seconds to 7days. |
void | setSyncSelfEnable(boolean syncSelfEnable) | Set that events supports multi-client synchronization. |
int | getEventType() | Get event type. |
int | getEventValue() | Get event value. |
String | getConfig() | Get the extension field of event. |
long | getExpiry() | Get expiry date of event. |
boolean | isBroadcastOnlineOnly() | Determine that event is broadcast to online subscribers only. |
String | getPublisherAccount() | Get event publisher. |
int | getPublisherClientType() | Get client type for event publication (See ClientType). |
long | getPublishTime() | Get event publishing time. |
String | getConfigByClient(int client) | Get event extension information published at a certain type of client. |
String | getNimConfig() | Get configuration information in reserved event, filled in from the server. |
Example
javaNIMClient.getService(EventSubscribeService.class).publishEvent(event);
Listening from subscribed events
The subscribed events are monitored using EventSubscribeServiceObserver
interface. Developers must keep the monitoring life cycle consistent with Application.
- API prototype
java/**
* Listen changes of event status.
*
* @param observer - Observer. The parameter is the latest event status.
* @param register - "true" indicates to register monitoring, "false" is to cancel monitoring.
*/
void observeEventChanged(Observer<List<Event>> observer, boolean register);
- Example
javaNIMClient.getService(EventSubscribeServiceObserver.class).observeEventChanged(new Observer<List<Event>>() {
@Override
public void onEvent(List<Event> events) {
// Processing.
}
}, true);
Querying event subscription
Support to query event subscription and query subscription relations of a certain event.
- API prototype
java/**
* Query subscription relationship of specified type of event.
* @param request - Query subscription information. The event type and account of event publisher must be filled in, and then subscription relationship of specified publisher will be queried.
* @return InvocationFuture - Configurable callback feature. It can be invoked only after request. If an error occurs, detailed error code will be returned.
*/
InvocationFuture<List<EventSubscribeResult>> querySubscribeEvent(EventSubscribeRequest request);
- Parameters
EventSubscribeResult
Description
Parameter | Description |
---|---|
eventType | Event type, input 1. |
expiry | Validity period of subscription, ranging from 60 seconds to 30 days, unit: second. |
time | Time of event subcription. |
publisherAccount | Account set of event publisher. |
- Example
javaNIMClient.getService(EventSubscribeService.class).querySubscribeEvent(request);
Online status events
Online status (online, abnormal disconnection, logout) is a built-in event of CommsEase system. Before the use, it is only required to make an application to the sales department and obtain the approval for the application. It is not required to actively publish event status. Typically, if A has subscribed an online status event from B, A may obtain B's online status after login: online, abnormal disconnection or logout.
Note:
- By calling the interface each time, up to 100 accounts can be subscribed. The interface should be called frequently for a larger number of accounts. In relation to online status event subscription, the maximum number of valid subscription accounts is no more than 3,000 for each accid.
- The subscription remains valid in 60 - 2,592,000 s (i.e. 60 s-30 days), and another subscription is required after expiry. In the event of repeated subscription within the validity term, the new validity term will replace the previous one.
- Online status events will be affected by push: if the application is cleared, but the vendor pushes (APNS, Xiaomi, Huawei, OPPO, VIVO, Meizu, FCM) are reachable, the disconnection event will not be triggered in default. If the offline status is required in such event, the developer should make modifications using
CommsEase Console>Select Application>IM Professional>Feature Configuration>Online Status Configuration
; if no integrated push is available or the push is unreachable, user disconnection will trigger the disconnection event. - Default value of online state event in system: 1 - login; 2 - logout; 3 - offline. If it is required to set the custom status, such as busy, please publish event.
- At login, the subscriber will receive the callback of the online event if the subscribed is online; but if the subscribed is offline, the subscriber will be unable to receive the callback of the offline event (subsequent login of the subscribed will trigger the online status event). We recommend setting the status of all accounts from online to offline at login, so that callback will be normally triggered no matter whether the other is online or the status is changed from offline to online.
- Friendship and online status are two different features of IM. When a friend is added, his/her online status will not be displayed.
- One-way subscription applies to online status event, to which both parties should subscribe respectively.
As mentioned above, online status event is a built-in event of CommsEase system, which the developer is not required to actively publish. After subscribing to the "type -1" event from B, A will receive the corresponding event at login if B is online; if B logs in to the account again and both B and A are online, A still can monitor the event.