Presence

Update time: 2023/02/01 16:56:36

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

/// 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
 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

 /// 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
 final result = await NimCore.instance.eventSubscribeService
            .unregisterEventSubscribe(eventSubscribeRequest);

Unsubscribe from events by event

Unsubscribe from all events by event type.

  • API prototype

 /// 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
 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

 /// 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

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

Listen to the subscribed events

  • API introduction

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

  • API prototype

 /// 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
NimCore.instance.eventSubscribeService.eventSubscribeStream.listen((List<Event> eventList) {

        });

Query event subscription

  • API introduction

Query event subscriptions

  • API prototype

 /// 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
final 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.

Was this page helpful?
Yes
No
  • Overview
  • Subscribe to events
  • Unsubscription
  • Unsubscribe from events by account
  • Unsubscribe from events by event
  • Publish events
  • Listen to the subscribed events
  • Query event subscription
  • Online status event