Authenticate and manage a session

OpenIM Android SDK uses initSDK() to initialize the local runtime and login() to establish the current user's session. Complete the service, user, and token preparation in Before you start, then add dependencies and permissions as described in Integrate for Android.

The complete flow is:

1. Create a stable OnConnListener in an application-level session component.
2. Call initSDK() and confirm that it returns true.
3. Register message, user, relationship, conversation, group, and call-signaling listeners before login.
4. Obtain the matching userID and token from a trusted backend, then call login().
5. Wait separately for login success and onConnectSuccess() before enabling operations that require the persistent connection.
6. On sign-out or account switching, call logout() and then clear application state owned by the current account.

The apiAddr, wsAddr, userID, and token used below are all provided by a trusted backend.

Initialize and handle the connection lifecycle

During the Application lifecycle, create the data directory, initialize the SDK, and provide the connection listener. Store connection state without recording tokens or complete service credentials in callback logs.

import android.app.Application;

import java.io.File;

import io.openim.android.sdk.OpenIMClient;
import io.openim.android.sdk.enums.LogLevel;
import io.openim.android.sdk.listener.OnConnListener;
import io.openim.android.sdk.models.InitConfig;

File dataDirectory = new File(application.getFilesDir(), "openim");
if (!dataDirectory.exists() && !dataDirectory.mkdirs()) {
    throw new IllegalStateException("Cannot create the OpenIM data directory.");
}

InitConfig config = new InitConfig(
    apiAddr,
    wsAddr,
    dataDirectory.getAbsolutePath()
);
config.logLevel = LogLevel.Info;
config.isLogStandardOutput = false;

OnConnListener connectionListener = new OnConnListener() {
    @Override
    public void onConnecting() {
        sessionState.setConnectionState("connecting");
    }

    @Override
    public void onConnectSuccess() {
        sessionState.setConnectionState("connected");
        sessionState.enableConnectedOperations();
    }

    @Override
    public void onConnectFailed(long code, String error) {
        sessionState.setConnectionState("failed");
        recordConnectionFailure(code, error);
    }

    @Override
    public void onKickedOffline() {
        sessionState.clearCurrentAccount();
        showSignedInElsewhereScreen();
    }

    @Override
    public void onUserTokenExpired() {
        requestNewTokenAndRelogin();
    }

    @Override
    public void onUserTokenInvalid(String reason) {
        sessionState.clearCurrentAccount();
        showSignInScreen(reason);
    }
};

boolean initialized = OpenIMClient.getInstance().initSDK(
    application,
    config,
    connectionListener
);

if (!initialized) {
    throw new IllegalStateException("OpenIMClientSDK initialization failed.");
}

A true return value means that the local SDK runtime initialized successfully. OnConnListener starts reporting persistent-connection state after login() is called.

Initialize the SDK only once in Application or an application-level session component. The Java wrapper exposes networkChanged() to ask Core to re-evaluate network connectivity; call it only when the application already has one centralized system-network observer, not from multiple screens.

Register business listeners before login

Listener registration uses set semantics, so a later call replaces the previous listener. Create stable listener instances in an application-level event dispatcher and forward events to screen state. See Send your first message for the complete message-listener registration and incremental merge example. User, relationship, conversation, group, and call-signaling listeners follow the same ownership rule.

The SDK does not expose remove or unset methods. During sign-out or account switching, the application event dispatcher must stop delivering callbacks to state owned by the previous account and replace the complete listener set before the next login.

Log in the current user

OpenIMClient.getInstance().login(new OnBase<String>() {
    @Override
    public void onError(int code, String error) {
        sessionState.setLoginState("failed");
        recordLoginFailure(code, error);
    }

    @Override
    public void onSuccess(String data) {
        sessionState.setLoginState("logged");
        sessionState.setCurrentUserID(userID);
    }
}, userID, token);

The successful login() callback means that the current login call completed. OnConnListener.onConnectSuccess() means that the persistent connection is available. Handle these as separate stages. Do not call login() concurrently or infer both states from only one callback.

Inspect login state

int loginStatus = OpenIMClient.getInstance().getLoginStatus();

if (loginStatus == LoginStatus.Logged) {
    String currentUserID = OpenIMClient.getInstance().getLoginUserID();
    restoreSessionFor(currentUserID);
}

getLoginStatus() and getLoginUserID() return local SDK snapshots and do not trigger connection callbacks. Sign out the previous account before logging in with a different account.

Handle token failure and forced logout

After onUserTokenExpired() or onUserTokenInvalid(), obtain new credentials for the current user from a trusted backend, then reauthenticate or return to the sign-in flow according to product policy. After onKickedOffline(), clear conversations, message views, unread counts, and other state owned by the current account. Do not treat forced logout as an explicit user sign-out.

These callbacks do not have a business-entity merge key. Isolate them by the current OpenIMClient singleton and logged-in user. Stop asynchronous work and screen subscriptions owned by the previous account before starting a new login.

Sign out and release the SDK

OpenIMClient.getInstance().logout(new OnBase<String>() {
    @Override
    public void onError(int code, String error) {
        recordLogoutFailure(code, error);
    }

    @Override
    public void onSuccess(String data) {
        sessionState.clearCurrentAccount();
    }
});

Successful completion means that the current SDK login session has signed out. Clear application state after the success callback. For account switching, wait for the previous logout before calling login() for the next account.

When the application will no longer use the SDK, release the runtime with:

OpenIMClient.getInstance().unInit();

unInit() is not a replacement for logout() and must not run when an ordinary screen is destroyed.

Next steps

• Before you start
• Integrate for Android
• Send your first message