SDKsAndroidIncludes Enterprise features

Events overview

The OpenIM Android SDK notifies applications of connection, synchronization, user, friendship, conversation, group, message, and call events via listeners. Each manager holds at most one listener instance; registering a new listener overwrites any previously registered listener. Manage listeners centrally within an application-scoped event coordinator and register them once before logging in, rather than inside activities, fragments, or Compose screens.

The core server connection lifecycle is handled by OnConnListener. Rather than configuring it through a domain manager, supply it during SDK initialization; for the full connection lifecycle implementation, see Authenticate and manage a session.

Centralized listener registration

The following example registers domain-specific listeners at an application-wide event center. Each listener handles callbacks strictly within its respective domain:

public final class OpenIMEventCenter {
    private final OpenIMClient client = OpenIMClient.getInstance();

    private final OnUserListener userListener = new OnUserListener() {
        // Handle user profile and presence updates
    };
    private final OnFriendshipListener friendshipListener = new OnFriendshipListener() {
        // Handle relationships, friend applications, and blocklist events
    };
    private final OnConversationListener conversationListener = new OnConversationListener() {
        // Handle conversations, unread counters, typing status, and data sync
    };
    private final OnGroupListener groupListener = new OnGroupListener() {
        // Handle group profiles, members, and group applications
    };
    private final OnAdvanceMsgListener messageListener = new OnAdvanceMsgListener() {
        // Handle new messages, revocations, deletions, edits, and read receipts
    };
    private final OnCustomBusinessListener businessListener = new OnCustomBusinessListener() {
        // Handle custom business messages
    };
    private final OnSignalingListener signalingListener = new OnSignalingListener() {
        // Handle calling invitations, participant state, and custom signaling
    };

    public void registerBeforeLogin() {
        client.userInfoManager.setOnUserListener(userListener);
        client.friendshipManager.setOnFriendshipListener(friendshipListener);
        client.conversationManager.setOnConversationListener(conversationListener);
        client.groupManager.setOnGroupListener(groupListener);
        client.messageManager.setAdvancedMsgListener(messageListener);
        client.messageManager.setCustomBusinessListener(businessListener);
        client.signalingManager.setSignalingListener(signalingListener);
    }
}

The Android SDK does not provide an unset or remove listener API. When logging out, switching accounts, or tearing down screens, stop propagating callbacks to stale UI controllers or former user state. Before logging in with a new account, re-register complete listener instances configured for the new session.

Event domain ownership

Scope	Listener	Documentation page
Connection, token expiration, and kick-offline	`OnConnListener`	Authenticate and manage a session
Current user profile	`OnUserListener`	Update the current user profile
Online presence	`OnUserListener`	Subscribe to user online status
Friendship status and profiles	`OnFriendshipListener`	Get the friend list
Friend applications	`OnFriendshipListener`	Get received friend applications
Blocklist	`OnFriendshipListener`	Block a user, Unblock a user
Conversation list	`OnConversationListener`	Get the conversation list
Total unread count	`OnConversationListener`	Get the total unread message count
Typing status	`OnConversationListener`	Report typing status
Group profiles, members, and applications	`OnGroupListener`	Group overview
New messages, offline messages, and online sync	`OnAdvanceMsgListener`	Receive messages
Message revocation	`OnAdvanceMsgListener`	Revoke a message
Message deletion	`OnAdvanceMsgListener`	Batch delete messages
Message modification	`OnAdvanceMsgListener`	Modify a message
Pinned messages	`OnAdvanceMsgListener`	Pin or unpin a message
Direct chat read receipts	`OnAdvanceMsgListener`	Mark a conversation as read
Custom business messages	`OnCustomBusinessListener`	Receive custom business messages
Calling sessions	`OnSignalingListener`	Handle calling events
Calling custom signaling	`OnSignalingListener`	Send custom signaling
SDK data synchronization	`OnConversationListener`	Listen for initialization synchronization

Listen for initialization synchronization

Data synchronization events belong to OnConversationListener, which also handles conversation list, unread count, and typing indicators. The following snippet illustrates the synchronization callbacks:

private final OnConversationListener conversationListener = new OnConversationListener() {
    @Override
    public void onSyncServerStart(boolean reinstall) {
        // Synchronization started: update sync status and display a loading indicator if appropriate
    }

    @Override
    public void onSyncServerProgress(long progress) {
        // Synchronization in progress: update progress indicators
    }

    @Override
    public void onSyncServerFinish(boolean reinstall) {
        // Synchronization finished: refresh UI components that depend on complete local datasets
    }

    @Override
    public void onSyncServerFailed(boolean reinstall) {
        // Synchronization failed: update error state and wait for retry or network reconnection
    }

    // Implement other conversation callbacks as needed...
};

The reinstall flag indicates whether synchronization is performing a full rebuild after local cache eviction: true indicates a fresh sync following app re-installation or cleared app storage, where local cached records do not exist; false indicates standard incremental synchronization on regular logins. The onSyncServerProgress callback provides completion percentage. When synchronization completes, query fresh data snapshots to populate active screens; on failure, reflect error status and wait for automatic retry or connection recovery.

Was this page helpful?