Subscribe to online status

This guide explains how to subscribe to, query, and listen for user connection status changes using the Nexconn SDK for Android.

Listen for subscription events

To receive real-time presence change notifications, use NCEngine.addUserHandler().

When handling subscription events, check the SubscribeType in the callback. For presence subscriptions, the type is SubscribeType.ONLINE_STATUS.

Kotlin

kotlin

NCEngine.addUserHandler("PRESENCE_HANDLER", object : UserHandler {
    override fun onSubscriptionChanged(event: SubscriptionChangedEvent) {
        if (event.subscribeType == SubscribeType.ONLINE_STATUS) {
            event.events.forEach { info ->
                val isOnline = info.details.any { it.eventValue == 1 }
                println("Presence changed for user: ${info.userId}, online: $isOnline")
            }
        }
    }

    override fun onSubscriptionSyncCompleted(event: SubscriptionSyncCompletedEvent) {
        if (event.subscribeType == SubscribeType.ONLINE_STATUS) {
            // Presence subscription sync complete
        }
    }

    override fun onSubscriptionChangedOnOtherDevices(event: SubscriptionChangedOnOtherDevicesEvent) {
        event.events.forEach { info ->
            println("Subscription changed on other device: ${info.userId}")
        }
    }
})

Java

Java

NCEngine.addUserHandler("PRESENCE_HANDLER", new UserHandler() {
    @Override
    public void onSubscriptionChanged(@NonNull SubscriptionChangedEvent event) {
        if (event.getSubscribeType() == SubscribeType.ONLINE_STATUS) {
            for (SubscribeStatusInfo info : event.getEvents()) {
                System.out.println("Presence changed: " + info.getUserId());
            }
        }
    }

    @Override
    public void onSubscriptionSyncCompleted(@NonNull SubscriptionSyncCompletedEvent event) {
        if (event.getSubscribeType() == SubscribeType.ONLINE_STATUS) {
            // Sync complete
        }
    }

    @Override
    public void onSubscriptionChangedOnOtherDevices(@NonNull SubscriptionChangedOnOtherDevicesEvent event) {
        // Handle other device subscription changes
    }
});

Remove the listener

Kotlin

kotlin

NCEngine.removeUserHandler("PRESENCE_HANDLER")

Java

Java

NCEngine.removeUserHandler("PRESENCE_HANDLER");

Subscribe to presence

Use NCEngine.userModule.subscribeEvent() with SubscribeEventParams to track specific users' connection status.

tip

• Up to 200 users per subscription call.
• Maximum total subscriptions: 1,000 users.
• Subscription duration: 60 to 2,592,000 seconds.
• Each user can be subscribed to by up to 5,000 users.

Kotlin

kotlin

val params = SubscribeEventParams(
    subscribeType = SubscribeType.ONLINE_STATUS,
    expiry = 180000,
    userIds = listOf("user1", "user2", "user3")
)

NCEngine.userModule.subscribeEvent(params) { failedIds, error ->
    if (error == null) {
        // Subscribed successfully
    } else {
        // failedIds contains user IDs that failed
    }
}

Java

Java

SubscribeEventParams params = new SubscribeEventParams(
    SubscribeType.ONLINE_STATUS,
    180000,
    Arrays.asList("user1", "user2", "user3")
);

NCEngine.userModule.subscribeEvent(params, (failedIds, error) -> {
    if (error == null) {
        // Subscribed successfully
    }
});

Query subscribed users' presence

Use NCEngine.userModule.getSubscribeUsersOnlineStatus() to query the current presence of subscribed users in bulk.

Kotlin

kotlin

val userIds = listOf("user1", "user2", "user3")

NCEngine.userModule.getSubscribeUsersOnlineStatus(userIds) { statuses, error ->
    if (error == null && statuses != null) {
        statuses.forEach { status ->
            println("User: ${status.userId}, Online: ${status.isOnline}")
        }
    }
}

Java

Java

List<String> userIds = Arrays.asList("user1", "user2", "user3");

NCEngine.userModule.getSubscribeUsersOnlineStatus(userIds, (statuses, error) -> {
    if (error == null && statuses != null) {
        for (UserOnlineStatus status : statuses) {
            System.out.println("User: " + status.getUserId() + ", Online: " + status.isOnline());
        }
    }
});

Unsubscribe from presence

Use NCEngine.userModule.unsubscribeEvent() to stop tracking a user's connection status.

Kotlin

kotlin

val params = UnsubscribeEventParams(
    subscribeType = SubscribeType.ONLINE_STATUS,
    userIds = listOf("user1", "user2", "user3")
)

NCEngine.userModule.unsubscribeEvent(params) { failedIds, error ->
    if (error == null) {
        // Unsubscribed successfully
    }
}

Java

Java

UnsubscribeEventParams params = new UnsubscribeEventParams(
    SubscribeType.ONLINE_STATUS,
    Arrays.asList("user1", "user2", "user3")
);

NCEngine.userModule.unsubscribeEvent(params, (failedIds, error) -> {
    if (error == null) {
        // Unsubscribed successfully
    }
});

Query subscription status for specific users

Use NCEngine.userModule.getSubscribeEvent() to check the subscription status of specific users. You can query up to 200 users at a time.

Kotlin

kotlin

val params = GetSubscribeEventParams(
    subscribeType = SubscribeType.ONLINE_STATUS,
    userIds = listOf("user1", "user2", "user3")
)

NCEngine.userModule.getSubscribeEvent(params) { subscribeInfoList, error ->
    if (error == null && subscribeInfoList != null) {
        subscribeInfoList.forEach { info ->
            println("Subscribed user: ${info.userId}, expires: ${info.expiry}")
        }
    }
}

Java

Java

GetSubscribeEventParams params = new GetSubscribeEventParams(
    SubscribeType.ONLINE_STATUS,
    Arrays.asList("user1", "user2", "user3")
);

NCEngine.userModule.getSubscribeEvent(params, (subscribeInfoList, error) -> {
    if (error == null && subscribeInfoList != null) {
        for (SubscribeStatusInfo info : subscribeInfoList) {
            System.out.println("Subscribed user: " + info.getUserId() + ", expires: " + info.getExpiry());
        }
    }
});

List subscribed users (paginated)

Use NCEngine.userModule.createSubscribeQuery() with SubscribeQueryParams to retrieve all subscribed users with pagination.

Kotlin

kotlin

val params = SubscribeQueryParams(SubscribeType.ONLINE_STATUS).apply {
    pageSize = 20
}

val query = NCEngine.userModule.createSubscribeQuery(params)

query.loadNextPage { page, error ->
    if (error == null && page != null) {
        page.data.forEach { info ->
            println("Subscribed user: ${info.userId}")
        }
        if (page.hasMore) {
            // Fetch next page
        }
    }
}

Java

Java

SubscribeQueryParams params = new SubscribeQueryParams(SubscribeType.ONLINE_STATUS);
params.setPageSize(20);

SubscribeQuery query = NCEngine.userModule.createSubscribeQuery(params);

query.loadNextPage((page, error) -> {
    if (error == null && page != null) {
        for (SubscriptionStatusInfo info : page.getData()) {
            System.out.println("Subscribed user: " + info.getUserId());
        }
        if (page.getHasMore()) {
            // Fetch next page
        }
    }
});