Subscribe to online status

This guide covers subscribing to, querying, and monitoring user online status.

Listen for subscription events

Register NCUserHandler after SDK initialization and before connecting:

Swift

swift

import NexconnChatSDK
final class SubscribeHandler: NSObject, UserHandler {}
let subscribeHandler = SubscribeHandler()
NCEngine.addUserHandler(identifier: "SUBSCRIBE_HANDLER", handler: subscribeHandler)
NCEngine.removeUserHandler(forIdentifier: "SUBSCRIBE_HANDLER")

Objective-C

Objective C

[NCEngine addUserHandlerWithIdentifier:@"SUBSCRIBE_HANDLER" handler:self];
[NCEngine removeUserHandlerForIdentifier:@"SUBSCRIBE_HANDLER"];

tip

Filter events by NCSubscribeType. The online status type is NCSubscribeTypeOnlineStatus.

Implement the handler callbacks:

Swift

swift

import NexconnChatSDK
func onSubscriptionSyncCompleted(_ event: SubscriptionSyncCompletedEvent) {
    // Sync completed after connection
    // event.type: subscription type (e.g., .onlineStatus)
}

func onSubscriptionChanged(_ event: SubscriptionChangedEvent) {
    // Status changed — check subscribeType for .onlineStatus
    for info in event.events {
        print("Subscription changed: \(info.userId)")
    }
}

func onSubscriptionChangedOnOtherDevices(_ event: SubscriptionChangedOnOtherDevicesEvent) {
    // Subscription changed on another device
    print("Changed on other devices: \(event.events.count)")
}

Objective-C

Objective C

- (void)onSubscriptionSyncCompleted:(NCSubscriptionSyncCompletedEvent *)event {
    // Sync completed after connection
    // event.type: subscription type (e.g., NCSubscribeTypeOnlineStatus)
}

- (void)onSubscriptionChanged:(NCSubscriptionChangedEvent *)event {
    // Status changed — check subscribeType for NCSubscribeTypeOnlineStatus
}

- (void)onSubscriptionChangedOnOtherDevices:(NCSubscriptionChangedOnOtherDevicesEvent *)event {
    // Subscription changed on another device
}

tip

All subscription APIs are on NCEngine.userModule.

Subscribe to online status

tip

• Max 200 users per subscription call
• Max 1,000 total subscriptions
• Each user can be subscribed to by up to 5,000 users

Swift

swift

import NexconnChatSDK
let params = SubscribeEventParams(subscribeType: .onlineStatus, userIds: ["user1", "user2", "user3"])
// Set expiry as appropriate (seconds)
params.expiry = 3600
NCEngine.userModule.subscribeEvent(params: params) { failedUserIds, error in
    // failedUserIds: IDs that failed (empty on full success)
}

Objective-C

Objective C

NCSubscribeEventParams *params = [[NCSubscribeEventParams alloc] init];
params.userIds = @[@"user1", @"user2", @"user3"];
// Set subscribeType and expiry as appropriate

[[NCEngine userModule] subscribeEventWithParams:params
                                   completion:^(NSArray<NSString *> *failedUserIds, NCError *error) {
    // failedUserIds: IDs that failed (empty on full success)
}];

Unsubscribe

Swift

swift

import NexconnChatSDK
let params = UnsubscribeEventParams(subscribeType: .onlineStatus, userIds: ["user1", "user2"])
NCEngine.userModule.unsubscribeEvent(params: params) { failedUserIds, error in
    // Unsubscribed
}

Objective-C

Objective C

NCUnsubscribeEventParams *params = [[NCUnsubscribeEventParams alloc] init];
params.userIds = @[@"user1", @"user2"];

[[NCEngine userModule] unsubscribeEventWithParams:params
                                     completion:^(NSArray<NSString *> *failedUserIds, NCError *error) {
    // Unsubscribed
}];

Query subscription events

Query up to 200 users per call:

Swift

swift

import NexconnChatSDK
let params = GetSubscribeEventParams()
params.subscribeType = .onlineStatus
params.userIds = ["user1", "user2"]
NCEngine.userModule.getSubscribeEvent(params: params) { events, error in
    // events: subscription event list
}

Objective-C

Objective C

NCGetSubscribeEventParams *params = [[NCGetSubscribeEventParams alloc] init];
params.userIds = @[@"user1", @"user2"];

[[NCEngine userModule] getSubscribeEventWithParams:params
                                      completion:^(NSArray<NCSubscriptionStatusInfo *> *events, NCError *error) {
    // events: subscription event list
}];

Query all subscriptions (paginated)

Use createSubscribeQueryWithParams: to create a paginated query object:

Swift

swift

import NexconnChatSDK
let params = SubscribeQueryParams()
params.subscribeType = .onlineStatus
params.pageSize = 20
let query = UserModule.createSubscribeQuery(params: params)
query.loadNextPage { page, error in
    // page?.data: current page of subscription events
}

Objective-C

Objective C

NCSubscribeQueryParams *params = [[NCSubscribeQueryParams alloc] init];
params.pageSize = 20;

NCSubscribeQuery *query = [NCUserModule createSubscribeQueryWithParams:params];
[query loadNextPageWithCompletion:^(NSArray<NCSubscriptionStatusInfo *> *events, NCError *error) {
    // events: current page of subscription events
}];

Query subscribed users' online status

Call getSubscribeUsersOnlineStatus to batch-query online status for subscribed users (max 200 per call):

Swift

swift

import NexconnChatSDK
NCEngine.userModule.getSubscribeUsersOnlineStatus(userIds: ["user1", "user2"]) { statusList, error in
    for userStatus in statusList ?? [] {
        let isOnline = userStatus.isOnline
        print("User \(userStatus.userId) is online: \(isOnline)")
    }
}

Objective-C

Objective C

[[NCEngine userModule] getSubscribeUsersOnlineStatusWithUserIds:@[@"user1", @"user2"]
                                                  completion:^(NSArray<NCSubscribeUserOnlineStatus *> *statusList, NCError *error) {
    for (NCSubscribeUserOnlineStatus *userStatus in statusList) {
        BOOL isOnline = userStatus.isOnline;
        NSLog(@"User %@ is online: %d", userStatus.userId, isOnline);
    }
}];

NCSubscribeUserOnlineStatus properties:

Property	Type	Description
userId	NSString	User ID
details	NSArray	Per-platform online status
isOnline	BOOL	YES if online on any platform