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 availabille 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: A subscribe to B ——>B publishes specific events——>A listen to the event change from B——>Handle business logic for events.

Note: You do not need to publish the built-in [presence event](/en/docs/TM5MzM5Njk/DIyMzExNDI?#Online Status Event) (type=1,value=1/2/3). This is handled by the CommsEase server.

Subscribe to events

objc@protocol NIMEventSubscribeManager <NSObject>
/**
 *  Subscribe event
 *
 *  @param request subscribe request
 *@param completion Completion callback
 * @discussion The request must contain type, expiry, and publishers fields
 */
- (void)subscribeEvent:(NIMSubscribeRequest *)request
            completion:(NIMEventSubscribeResponseBlock)completion;
@end            

Properties

Parameter	Type	Description
request	NIMSubscribeRequest	Request to subscribe to an event.
completion	NIMEventSubscribeResponseBlock	Callback for completion

NIMSubscribeRequest

objc@interface NIMSubscribeRequest : NSObject

/**
 * Event type. Set the value to 1.
 */
@property (nonatomic, assign) NSInteger type;


/**
 * The validity period of a subscription. Value range: 60 seconds to 7 days. Unit: seconds. The default value is 7 days.,
 */
@property (nonatomic, assign) NSTimeInterval expiry;


/**
 * Specify whether to synchronize the event status value immediately after subscription
 * @discussion The default value is NO. If the value is set to YES , you will receive a callback - (void)onRecvSubscribeEvent:
 */
@property (nonatomic, assign) BOOL syncEnabled;


/**
 * IDs of publishers of the event. Up to 100 IDs are allowed.
 * @discussion Since the same event may be triggered by different users, you can only subscribe to events published by users in the array.
 */
@property (nonatomic, copy) NSArray *publishers;

@end

Unsubscription

Unsubscribe from all events

objc@protocol NIMEventSubscribeManager <NSObject>
/**
 *  Unsubscribe event
 *
 *  @param request unsubscribe request
 *@param completion Completion callback
 * @discussion The type field must be specified in the request. If the publishers field is not set, all subscription relationships of the specified event will be cancelled.
 */
- (void)unSubscribeEvent:(NIMSubscribeRequest *)request
              completion:(NIMEventSubscribeResponseBlock)completion;
@end              

Properties

Parameter	Type	Description
request	NIMSubscribeRequest	Request to unsubscribe from an event.
completion	NIMEventSubscribeResponseBlock	Callback for completion

Before calling the subscribe/unsubscribe interface, you must construct the NIMSubscribeRequest object used to subscribe to events.

The subscription requests must contain the type, expiry, and publishers fields The publishers field only supports up to 100 account IDs. In some scenarios such as online status, the number of subscribers will exceed the limit. You must call this interface multiple times to meet the business requirements. For more information, see - (void)subscribeOnlineState of NTESSubscribeManager in the Demo.

To unsubscribe from events, the type field must be specified in the request. If the publishers field is empty, all subscription relationships of the specified events will be cancelled.

Publish events

objc@protocol NIMEventSubscribeManager <NSObject>
/**
 *  Publish an event
 *
 * @param event The event to be published. The event can be subscribed by others
 *@param completion Completion callback
 */
- (void)publishEvent:(NIMSubscribeEvent *)event
          completion:(NIMEventSubscribeBlock)completion;
@end          

Properties

Parameter	Type	Description
event	NIMSubscribeEvent	The event to be published. The event can be subscribed by others
completion	NIMEventSubscribeBlock	Callback for completion

To publish an event, you must construct an Event object and the required fields include type and value. type only supports "presence events", NIMSubscribeSystemEventTypeOnline.

NIMSubscribeEvent object

objc@interface NIMSubscribeEvent : NSObject

/**
 *  Event ID
 */
@property (nonatomic, copy, readonly) NSString *eventId;


/**
 *  Event starter
 */
@property (nullable, nonatomic, copy, readonly) NSString *from;


/**
 *  Timestamp of an event
 */
@property (nonatomic, assign, readonly) NSTimeInterval timestamp;


/**
 * Event type, set the value to 1.
 */
@property (nonatomic, assign) NSInteger type;


/**
 * The state value for the event. Set a value greater than 10,000. The value range 1-9999 belongs to CommsEase.
 */
@property (nonatomic, assign) NSInteger value;


/**
 * The validity period of an event. Value range: 60 seconds to 7 days. Unit: seconds. The default value is 7 days.
 */
@property (nonatomic, assign) NSTimeInterval expiry;


/**
 * Specify whether to broadcast messages only to online users
 * @discussion The default value is YES. If the value is set to NO, the event will be synchronized after the subscriber logs in.
 */
@property (nonatomic, assign)  BOOL sendToOnlineUsersOnly;


/**
 * Specify whether to support multiple device synchronization
 *  @discussion The default value is YES
 */
@property (nonatomic, assign)  BOOL syncEnabled;


/**
 * Additional information for the subscribed event, NIMSubscribeOnlineInfo when NIMSubscribeSystemEventTypeOnline is subscribed.
 */
@property (nonatomic, strong, readonly)  id subscribeInfo;

@end

Listen to the subscribed events

When the subscribed event is delivered from the CommsEase server, monitor the event using the -onRecvSubscribeEvents callback. Implement the –onRecvSubscribeEvents callback of the NIMEventSubscribeManagerDelegate protocol: Method

Prototype

objc@protocol NIMEventSubscribeManagerDelegate <NSObject>
/**
 *  Callback for receiving all subscribed events
 *  @param events Broadcast NIMSubscribeEvent list
 */
- (void)onRecvSubscribeEvents:(NSArray *)events;
@end

Query event subscription

objc@protocol NIMEventSubscribeManager <NSObject>
/**
 *  Query subscribed events
 *
 *  @param request Request to query subscribed events
 *@param completion Completion callback
 */
- (void)querySubscribeEvent:(NIMSubscribeRequest *)request
                 completion:(NIMEventSubscribeQueryBlock)completion;
@end                 

Properties

Parameter	Type	Description
request	NIMSubscribeRequest	Request to unsubscribe from an event.
completion	NIMEventSubscribeQueryBlock	Callback for completion

Before calling the subscribe/unsubscribe interface, you must construct the NIMSubscribeRequest object used to subscribe to events. The type and publishers fields must be specified in the request. Up to 100 users are allowed.

The SDK does not support querying the subscription relationship between the account of the current user and other user accounts. The upper layer must manage the user IDs to be queried, and complete the query by calling this interface multiple times.

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: A [subscribe to events](/en/docs/TM5MzM5Njk/DIyMzExNDI?#subscribe to events) of B. When A logs in, the online status of B is retrieved, 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](/en/docs/TM5MzM5Njk/DIyMzExNDI?#Publish Event).
• 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. For the business logic of the specific online status, see NTESSSubscribeManager in the Demo.