Instant Messaging
iOS
Getting Started
Product Introduction
Overview
Features
Limits
Feature overview
Account Integration and Login
Basic Message Features
Group Chat
Chat Room
Chat Room Tags
Multi-device Login
Statistics Monitoring
Development Integration
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
System Notification
APNs
Team Chat
Superteam
Chat Room
Anti-spam
Chat Extension
Miscellaneous Features
Reference Documents
Configuration Instruction for PushKit
Push Configuration for Apple iOS
API References
iOS API Reference
Status Codes

Online Status Subscription

Update time: 2021/12/06 15:04:54

Overview

Users may implement the design mode programming method of "Publish-Subscribe" by publishing and subscribing to events. This can be used to subscribe for the online status of specified users, users' personalized information, etc.

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 ——> handles 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.

Subscribe to events

@protocol NIMEventSubscribeManager <NSObject>
/**
 * Subscription event
 *
 * @param request - Subscription request
 * @param completion  A callback for completion
 * @discussion - The field "type", "expiry" and "publishers" must be contained in request.
 */
- (void)subscribeEvent:(NIMSubscribeRequest *)request
            completion:(NIMEventSubscribeResponseBlock)completion;
@end            

Parameter List

Parameter Type Description
request NIMSubscribeRequest Subscribe request
completion NIMEventSubscribeResponseBlock Callback completion

NIMSubscribeRequest Prototype

@interface NIMSubscribeRequest : NSObject

/**
 * Event type, input 1.
 */
@property (nonatomic, assign) NSInteger type;


/**
 * Period of validity for subscription, with range 60s to 30d, unit: s. If it is expired, a subscription will be canceled automatically.
 */
@property (nonatomic, assign) NSTimeInterval expiry;


/**
 * It determines to synchronize event state value immediately after subscription.
 * @discussion - The value is "NO" by default. If it is set to "YES", the event callback (void)onRecvSubscribeEvent: will be returned.
 */
@property (nonatomic, assign) BOOL syncEnabled;


/**
 * ID array of event publishers, with limit 100
 * @discussion - The same event may be published by different users, so that only events published by users in array can be subscribed.
 */
@property (nonatomic, copy) NSArray *publishers;

@end

Unsubscribe from events

Cancel the current subscription.

@protocol NIMEventSubscribeManager <NSObject>
/**
 * Cancel subscription event
 *
 * @param request - Cancel subscription request
 * @param completion  A callback for completion
 * @discussion - The type field must be filled in the request. If the field "publishers" is not filled in, all subscription relationships of the designated event will be canceled.
 */
- (void)unSubscribeEvent:(NIMSubscribeRequest *)request
              completion:(NIMEventSubscribeResponseBlock)completion;
@end              

Parameter List

Parameter Type Description
request NIMSubscribeRequest Unsubscribe request
completion NIMEventSubscribeResponseBlock Callback completion

Before calling the subscribe/unsubscribe event API, it is required to construct the subscription request object NIMSubscribeRequest.

For subscription events, fields like type, expiry, publishers must be filled in subscription request. publishers The field supports 100 IDs at most. Some scenes such as online status, the number of subscribers will exceed the limit. It is required to call The API multiple times as required for business. Refer to NTESSubscribeManager's - (void)subscribeOnlineState method for detail.

In unsubscribe, the field type is required in subscribe request; if the field publishers is blank, all the subscriptions will be canceled for specified events.

Publish events

@protocol NIMEventSubscribeManager <NSObject>
/**
 * Publish event
 *
 * @param event - It is an event that shall be broadcast. The event can be subscribed to by others.
 * @param completion  A callback for completion
 */
- (void)publishEvent:(NIMSubscribeEvent *)event
          completion:(NIMEventSubscribeBlock)completion;
@end          

Parameter List

Parameter Type Description
event NIMSubscribeEvent Events to be broadcast may be subscribed by others
completion NIMEventSubscribeBlock Callback completion

Before publish, it is necessary to construct the object NIMSubscribeEvent, and the fields type and value are required. type Currently only supports "online status event", i.e. NIMSubscribeSystemEventTypeOnline.

NIMSubscribeEvent Object prototype

@interface NIMSubscribeEvent : NSObject

/**
 * Event ID. It is not required when an event is published.
 */
@property (nonatomic, copy, readonly) NSString *eventId;


/**
 * Event publisher. It is not required when an event is published.
 */
@property (nullable, nonatomic, copy, readonly) NSString *from;


/**
 * Publishing time of an event. It is not required when an event is published.
 */
@property (nonatomic, assign, readonly) NSTimeInterval timestamp;


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


/**
 * State value of an event. : The value is 10000 and above (1-9999 is pre-defined value range in CommsEase. Developers cannot use the value range).
 */
@property (nonatomic, assign) NSInteger value;


/**
 * Period of validity for an event, with range 60s to 7d, unit: s. It is 7d by default.
 */
@property (nonatomic, assign) NSTimeInterval expiry;


/**
 * It determines that an event is broadcast to online subscribers only.
 * @discussion - The value is "YES" by default. If it is set to "NO", the event will be synchronized after login by a subscriber.
 */
@property (nonatomic, assign) BOOL sendToOnlineUsersOnly;


/**
 * It determines that an event supports multi-client synchronization.
 * @discussion - The value is "YES" by default.
 */
@property (nonatomic, assign) BOOL syncEnabled;


/**
 * It is extra information about the subscription event. If the subscription event is NIMSubscribeSystemEventTypeOnline, the value is NIMSubscribeOnlineInfo.
 */
@property (nonatomic, strong, readonly) id subscribeInfo;

@end

Monitor subscribed event

Monitor the subscribed event which is pushed down from CommsEase server by callback from -onRecvSubscribeEvents. Under the NIMEventSubscribeManagerDelegate protocol, please implement the –onRecvSubscribeEvents: method.

Prototype

@protocol NIMEventSubscribeManagerDelegate <NSObject>
/**
 * Returned callback for subscribed event
 * @param events - NIMSubscribeEvent list of broadcast event
 */
- (void)onRecvSubscribeEvents:(NSArray *)events;
@end

Query the relations among subscribed events

@protocol NIMEventSubscribeManager <NSObject>
/**
 * Query subscription event
 *
 * @param request - Query request
 * @param completion  A callback for completion
 */
- (void)querySubscribeEvent:(NIMSubscribeRequest *)request
                 completion:(NIMEventSubscribeQueryBlock)completion;
@end                 

Parameter List

Parameter Type Description
request NIMSubscribeRequest Unsubscribe request
completion NIMEventSubscribeQueryBlock Callback completion

SDK provides an API for querying the subscription relationship between the account and the specified account. Before calling The API, it is necessary to construct the subscribe request object NIMSubscribeRequest. The fields type and publishers are required. The number of persons to be queried is up to 100.

At present, the subscription relationship between the account and all accounts cannot be queried. The upper level should well maintain the user IDs to be queried, and complete the query by calling The API multiple times.

Online status event

Online status (online, abordinary 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. if A has subscribed an online status event from B, A may obtain B's online status after login: online, abordinary disconnection or logout.

Note:

  • By calling The API each time, up to 100 accounts can be subscribed. The API 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 not 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 an event, the developer should make modifications with 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 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 an online status event, to which both parties should subscribe respectively.

As mentioned above, an online status event is a built-in event of CommsEase system, which the developer is not required to actively publish. After subscribing 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. The business logic of the specific online status may be implemented in reference to NTESSubscribeManager of Demo.

Was this topic helpful?
Yes
No
  • Overview
  • Subscribe to events
  • Unsubscribe from events
  • Publish events
  • Monitor subscribed event
  • Query the relations among subscribed events
  • Online status event