Subscribe to the presence status

Overview

You can implement the "publish-subscribe" design pattern with event publishing and subscription. App users can subscribe to the online status of a specified user and personalized user information.
Only the event with type=1 are availability for subscription. You can customize the value for specific business needs. A value corresponds to an event state. Values between 1 and 9999 belong to CommsEase. You cannot use these value for your use..
Implementation: User A subscribe to User B’s presence——>User B publishes a specific event——>User A listens to the event for the presence changes from User B——>Handle business logic for events.
**Note: You do not need to publish the built-in presence events (type=1,value=1/2/3). This is handled by the CommsEase server. **

Subscribe to events

• API introduction

Subscribe to a specific event published by specific users. Whether it is a built-in online status event or a custom event, you must subscribe to events using this interface. Each account can subscribe to a maximum of 3,000 valid accounts. For the subscription validity period, since multi-device subscriptions (the same account subscribe to events on different types of devices) will override this period. Make sure you keep the same subscription period on all devices. Note that for performance purpose, if users subscribe to the same event published by the same account within 30 seconds, the event is not triggered immediately.

• API prototype

dart
/// Subscribe to events
/// [request] The request to subscribe to a specific event. The event type, publisher account, and the expiration duration must be specified.

 Future<NIMResult<List<String>>> registerEventSubscribe(
      EventSubscribeRequest request) async

• Parameters

EventSubscribeRequest representation

Parameter	Type	Description
eventType	int	Event type. Set the value to 1.
expiry	int	The expiration duration for the subscription. Value range: 60s to 30 days. Unit: seconds.
syncCurrentValue	bool	Specify whether to synchronize the event state value immediately after subscription. The default value is false.
publishers	List<String>	Array of accounts that publish events.

The subscription requests must contain the eventType, expiry, and publishers fields

• Example

dart final result = await NimCore.instance.eventSubscribeService
            .registerEventSubscribe(eventSubscribeRequest);

Unsubscription

Unsubscribe from events by account

• API introduction

You can unsubscribe from events. The requests for unsubscription must contain the eventType and publishers fields.

• API prototype

dart
 /// Unsbscribe from a specified event by account
 ///  [request] The request to unsubscribe from a specific event. Only the event type and publisher accounts are required.
 
 Future<NIMResult<bool>> unregisterEventSubscribe(
      EventSubscribeRequest eventSubscribeRequest)

• Example

dart final result = await NimCore.instance.eventSubscribeService
            .unregisterEventSubscribe(eventSubscribeRequest);

Unsubscribe from events by event

Unsubscribe from all events by event type.

• API prototype

dart
 /// Unsubscribe from all specified events
 ///  [request] The request to unsubscribe from a specific event. Only event type is required.
 
Future<NIMResult<bool>> batchUnSubscribeEvent( EventSubscribeRequest request);

• Example

dart final result = await NimCore.instance.eventSubscribeService
            .batchUnSubscribeEvent(eventSubscribeRequest);

Publish events

• API introduction

Publishes events for subscribers. If the built-in online status event cannot meet the requirements or you need some custom events, this interface can be used to publish events.

• API prototype

dart
 /// Publish an event.
 /// [event] Event
 
Future<NIMResult<bool>> publishEvent(Event event);

To publish an event, you must construct an Event object and the required fields include:

• eventType: set the value to 1.
• eventValue: set a value greater than 10,000. The value range 1-9999 belongs to CommsEase.

Event interface:

Type	Event Field	Description
eventType	int	Set the event type used to publish an event
eventValue	int	Set the event value used to publish an event
config	String	Set the extension field of the event, configured by the client when publishing the event
broadcastOnlineOnly	bool	Whether an event is broadcast to online subscribers.
expiry	int	Set the validity period of an event, in seconds, and the value range is 60s to 7days.
isBroadcastOnlineOnly	bool	Whether the event is published for online users only.
publisherAccount	String	The account that publish events.
publisherClientType	int	The client type of a publisher. For more information, see ClientType
publishTime	int	The time when an event is published.
multiClientConfigMap	Map<int, String>	Event extension information published by a specified type of clients.
String	nimConfig	the configuration information in the reserved event, specified by the server.

Example

dartawait NimCore.instance.eventSubscribeService.publishEvent(event);

Listen to the subscribed events

• API introduction

Listen to subscribed events usingStreamController<List<Event>> eventSubscribeStream.

• API prototype

dart
 /// Listen to event state changes
 /// [observer] The observer. The parameter is the event state
 /// [register] true: register the observer. false: unregister the observer.
 
  final StreamController<List<Event>> eventSubscribeStream =
      StreamController<List<Event>>.broadcast();

• Example

dartNimCore.instance.eventSubscribeService.eventSubscribeStream.listen((List<Event> eventList) {

        });

Query event subscription

• API introduction

Query event subscriptions

• API prototype

dart
 /// Query the subscription relationship to specific events.
 /// [request] The request to query the subscriotion info. The event type and publisher accounts are required. The information about subscription to specific events published by the specified publisher can be queried. 
Future<NIMResult<List<EventSubscribeResult>>> querySubscribeEvent(
      EventSubscribeRequest request)

• Parameters

EventSubscribeResult representation

Parameter	Type	Description
eventType	int	Event type. Set the value to 1
expiry	int	The expiration date for the subscription. Value range: 60s to 30 days. Unit: seconds.
time	int	The time when the event is subscribed
publisherAccount	List<String>	The accounts that publish events.

• Example

dartfinal result = await NimCore.instance.eventSubscribeService
            .querySubscribeEvent(request);

Online status event

The online status, such as Online, Disconnected, and Offline, is a built-in event. You can request to activate the service by contact sales for help. You can use the service after it is activated. You do not need to publish the event. Use case: User A subscribes to the presence events from User B. When User A logs in, the presence status of User B is retrieved, such as Online, Disconnected or Offline.

Notes

• You can only subscribe to a maximum of 100 accounts each time you call the interface, and multiple calls are required for a large number of accounts. Each account has a maximum of 3,000 valid subscriptions.
• The subscription is valid for 60 - 2592000 seconds (60 seconds to 30 days), and you need to re-subscribe to the event after it expires. If the subscription is repeated without expiration, the new validity period will overwrite the previous validity period.
• Online status events is affected by push services: If the push services provided by APNs, FMC, XIAOMI, HUAWEI, OPPO, VIVO, and MEIZU is working when your app is cleaned up, the user is still deemed online by default. If you want to change the state to Offline, go to CommsEase Console > Select Application > IM Pro > Features > Presence. If the push service is not integrated or fails, the user is offline when getting disconnected.
• The values for presence events: 1 - Online, 2 - Offline, 3 - Disconnected. If you want to set a custom status, such as Busy, you can publish events.
• If the subscriber is online, subscribers will receive the status returned by the callback; If the publisher is offline, the subscriber cannot receive the status returned by the callback. When the publisher logs in, the presence event will trigger the callback. You can set the presence status of all accounts to offline when logging in. This way, the callback can be triggered no matter whether the status changes from online to offline or offline to online.**
• The friend relationship and presence are two separate features of IM. Friends will not display the presence status without subscription.
• The subscription behavior is unidirectional. All users must subscribe to presence events separately.

The presence event is a built-in event. You do not need to publish the event. If A subscribes to B's presence event, A will receive the corresponding event for B’s status. If B logs in again and A is also online, the callback can still be triggered.