Authenticate and manage a session

Initialize the local OpenIM Flutter SDK with initSDK(), then establish the current user's session with login(). Before authenticating, complete the server, user, token, and mobile environment preparations described in Before you start.

The complete flow is:

1. Call initSDK() and provide an OnConnectListener.
2. Obtain the userID, token, apiAddr, and wsAddr from the application backend.
3. Call login(), wait for its Future, and then wait for onConnectSuccess.
4. Once the connection is available, query user, friend, conversation, group, and message data.
5. When signing out or switching accounts, call logout() and then clear application state for the current account.

Obtain credentials for the current user

Obtain the current user's userID and token, together with the environment's apiAddr and wsAddr, from the application backend. See Before you start for the required data.

userID is an OpenIMSDK user identifier and must correspond to the token. The mobile client consumes credentials returned by the backend; it does not create OpenIM users or issue tokens.

Initialize and configure the connection lifecycle

Set the connection listener through initSDK() before logging in so the app does not miss state changes during login.

final initialized = await OpenIM.iMManager.initSDK(
  platformID: platformID,
  apiAddr: apiAddr,
  wsAddr: wsAddr,
  dataDir: dataDir,
  listener: OnConnectListener(
    onConnecting: () {
      setConnectionState('connecting');
    },
    onConnectSuccess: () {
      setConnectionState('connected');
    },
    onConnectFailed: (code, errorMsg) {
      setConnectionState('failed');
      logConnectionFailure(code, errorMsg);
    },
    onKickedOffline: () {
      clearCurrentSession();
      showSignedInElsewhereDialog();
    },
    onUserTokenExpired: () async {
      await refreshSessionAndRelogin();
    },
    onUserTokenInvalid: () {
      redirectToSignIn();
    },
  ),
);

if (initialized != true) {
  throw StateError('OpenIMClientSDK initialization failed.');
}

Parameters

When the initSDK() Future succeeds and returns true, local SDK initialization is complete. This does not mean that a user is logged in or that the persistent connection is available. Initialize the SDK centrally once per application process; do not start separate initialization flows from multiple widgets.

initSDK() retains the OnConnectListener, and the SDK does not expose a method for removing it. Keep one listener in a central owner and avoid reinitializing the SDK during widget rebuilds.

Log in the current user

final UserInfo currentUser = await OpenIM.iMManager.login(
  userID: session.userID,
  token: session.token,
);

setCurrentUser(currentUser);

Parameters

After the login() Future succeeds, it returns the current account's UserInfo, which means that the login call and the SDK's internal profile read have completed. onConnectSuccess separately means that the persistent connection is available. Do not collapse these two stages into one check.

Do not call login() concurrently. Reuse an in-flight Future from the login button, or disable repeated submission based on login state.

Inspect login state

final status = await OpenIM.iMManager.getLoginStatus();

if (status == LoginStatus.logged) {
  final currentUserID = await OpenIM.iMManager.getLoginUserID();
  restoreSessionFor(currentUserID);
}

getLoginUserInfo() returns the UserInfo cached by the Flutter wrapper during the current login. To read the current account's profile from the SDK again, use userManager.getSelfUserInfo().

After the getLoginStatus() and getLoginUserID() futures succeed, their results can establish a snapshot of the current login state. The queries themselves do not trigger connection callbacks. getLoginUserID() can verify that the application account and SDK account match, but it does not replace application authentication.

When switching accounts, do not overwrite the current login with new parameters. Wait for logout() to complete, clear the previous account's state, and then log in with the new account's userID and token.

Handle token errors and forced sign-out

When a token expires or becomes invalid, obtain new credentials from the application backend and log in again or enter the application's sign-in flow. onKickedOffline indicates that another device or the server forced the current account offline; it is distinct from an explicit user sign-out.

The Flutter login flow passes one OpenIMSDK token to login(); it does not distinguish client-side “access tokens” from “session tokens.” Token issuance, expiration, refresh, and revocation are determined by the application backend and OpenIMServer configuration.

These callbacks have no business-entity merge key. Isolate their state by the current SDK instance and logged-in user. Before switching accounts, clear the previous account's state so old asynchronous work cannot update the new account's pages.

Sign out deliberately

await OpenIM.iMManager.logout();
clearCurrentSession();

A successful logout() Future means that the current SDK login session has ended. To switch accounts, wait for the previous account to log out, clear its state, and then call login() for the new account.

For deliberate sign-out, the successful Future, connection callbacks, and business-page cleanup are separate stages. Wait for logout() first, then clear the current account's conversation list, message views, unread counts, and application state. Do not use one connection callback alone to decide that sign-out has completed.

To release the SDK completely, call unInitSDK() after sign-out finishes. It releases the SDK runtime; it does not replace logout() and should not be called merely because an ordinary page is disposed.

Next steps

• Before you start
• Send your first message
• Events overview
• Logging