User event handler

Use UserHandler to receive user-level event callbacks — including subscription event changes, friend relationship changes, and multi-device sync notifications.

Register and remove the handler

Kotlin

kotlin

// Register
NCEngine.addUserHandler("MY_USER_HANDLER", object : UserHandler {
    override fun onFriendAdd(event: FriendAddEvent) { /* ... */ }
})

// Remove
NCEngine.removeUserHandler("MY_USER_HANDLER")

Java

Java

// Register
NCEngine.addUserHandler("MY_USER_HANDLER", new UserHandler() {
    @Override
    public void onFriendAdd(@NonNull FriendAddEvent event) { /* ... */ }
});

// Remove
NCEngine.removeUserHandler("MY_USER_HANDLER");

Implement UserHandler

All methods have default empty implementations. Override only the callbacks you need.

Kotlin

kotlin

NCEngine.addUserHandler("MY_USER_HANDLER", object : UserHandler {

    // Subscription event changed (e.g., online status update)
    override fun onSubscriptionChanged(event: SubscriptionChangedEvent) {
        for (info in event.events) {
            println("User ${info.userId} status changed")
        }
    }

    // Subscription data sync completed
    override fun onSubscriptionSyncCompleted(event: SubscriptionSyncCompletedEvent) {
        println("Subscription synced for type: ${event.type}")
    }

    // Subscription info changed on another device
    override fun onSubscriptionChangedOnOtherDevices(event: SubscriptionChangedOnOtherDevicesEvent) {
        println("Subscription changed on another device: ${event.events.size} events")
    }

    // Friend added
    override fun onFriendAdd(event: FriendAddEvent) {
        println("Friend added: ${event.userId}")
    }

    // Friends deleted
    override fun onFriendDelete(event: FriendDeleteEvent) {
        println("Friends deleted: ${event.userIds}")
    }

    // Friend application status changed
    override fun onFriendApplicationStatusChanged(event: FriendApplicationStatusChangedEvent) {
        println("Friend application from ${event.userId} status: ${event.applicationStatus}")
    }

    // All friends cleared (server-initiated only)
    override fun onFriendCleared(event: FriendClearedEvent) {
        println("All friends cleared at: ${event.operationTime}")
    }

    // Friend info changed on another device (multi-device sync)
    override fun onFriendInfoChangedSync(event: FriendInfoChangedSyncEvent) {
        println("Friend info synced for: ${event.userId}")
    }
})

Java

Java

NCEngine.addUserHandler("MY_USER_HANDLER", new UserHandler() {

    @Override
    public void onSubscriptionChanged(@NonNull SubscriptionChangedEvent event) {
        for (SubscriptionStatusInfo info : event.getEvents()) {
            System.out.println("User " + info.getUserId() + " status changed");
        }
    }

    @Override
    public void onSubscriptionSyncCompleted(@NonNull SubscriptionSyncCompletedEvent event) {
        System.out.println("Subscription synced for type: " + event.getType());
    }

    @Override
    public void onSubscriptionChangedOnOtherDevices(@NonNull SubscriptionChangedOnOtherDevicesEvent event) {
        System.out.println("Subscription changed on another device");
    }

    @Override
    public void onFriendAdd(@NonNull FriendAddEvent event) {
        System.out.println("Friend added: " + event.getUserId());
    }

    @Override
    public void onFriendDelete(@NonNull FriendDeleteEvent event) {
        System.out.println("Friends deleted: " + event.getUserIds());
    }

    @Override
    public void onFriendApplicationStatusChanged(@NonNull FriendApplicationStatusChangedEvent event) {
        System.out.println("Friend application status: " + event.getApplicationStatus());
    }

    @Override
    public void onFriendCleared(@NonNull FriendClearedEvent event) {
        System.out.println("All friends cleared at: " + event.getOperationTime());
    }

    @Override
    public void onFriendInfoChangedSync(@NonNull FriendInfoChangedSyncEvent event) {
        System.out.println("Friend info synced for: " + event.getUserId());
    }
});

Callback reference

Callback	Event type	Trigger
onSubscriptionChanged	SubscriptionChangedEvent	One or more subscribed events changed (e.g., online status). Iterate event.events.
onSubscriptionSyncCompleted	SubscriptionSyncCompletedEvent	Subscription data sync completed. event.type identifies the subscription type.
onSubscriptionChangedOnOtherDevices	SubscriptionChangedOnOtherDevicesEvent	Subscription info changed on another device. Iterate event.events.
onFriendAdd	FriendAddEvent	A friend was added. event.userId for the friend's ID.
onFriendDelete	FriendDeleteEvent	One or more friends were removed. event.userIds for affected IDs.
onFriendApplicationStatusChanged	FriendApplicationStatusChangedEvent	A friend request status changed. event.userId and event.applicationStatus.
onFriendCleared	FriendClearedEvent	All friends were cleared by a server-side operation. event.operationTime for the timestamp.
onFriendInfoChangedSync	FriendInfoChangedSyncEvent	Friend info changed on another device (multi-device sync).

UserSettingsHandler

To receive user-level settings sync events, register a UserSettingsHandler separately:

Kotlin

kotlin

// Register
NCEngine.addUserSettingsHandler("MY_SETTINGS_HANDLER", object : UserSettingsHandler {
    override fun onUserSettingsSyncCompleted(event: UserSettingsSyncCompletedEvent) {
        if (event.error == null) {
            // User settings synced successfully
        } else {
            println("User settings sync failed: ${event.error}")
        }
    }
})

// Remove
NCEngine.removeUserSettingsHandler("MY_SETTINGS_HANDLER")

Java

Java

// Register
NCEngine.addUserSettingsHandler("MY_SETTINGS_HANDLER", new UserSettingsHandler() {
    @Override
    public void onUserSettingsSyncCompleted(@NonNull UserSettingsSyncCompletedEvent event) {
        if (event.getError() == null) {
            // User settings synced successfully
        }
    }
});

// Remove
NCEngine.removeUserSettingsHandler("MY_SETTINGS_HANDLER");

Related topics

• User overview
• Subscribe to presence
• Friend management