OpenIMSDKDocs

Type at least two characters to search titles and routes.

EN

Language

ENEnglishEnglish docs简中简体中文中文文档
Browse SDKs · Android
Platform
SDKsAndroid

Before you start

Prepare your OpenIMServer, credentials, and Android project environment before initializing, authenticating, or sending messages.

Copy

Before integrating the OpenIM Android SDK into a native Android app, verify that you have an accessible OpenIMServer deployment, valid user authentication credentials, and an Android project configured to meet SDK build requirements. These prerequisites apply to both Authenticate and manage a session and Send your first message.

Prepare OpenIMServer

If you have not deployed an OpenIMServer instance yet, follow the Docker deployment guide. Ensure that both physical Android devices and emulators can reach the following server endpoints:

EndpointDescription
apiAddrOpenIMServer HTTP API endpoint used for authentication, data synchronization, and resource requests.
wsAddrOpenIMServer WebSocket endpoint used for persistent connections and real-time events.

Do not verify endpoints only on your development workstation. In the Android emulator, localhost points to the virtual device itself, not your host computer. When running OpenIMServer locally on your development machine, forward the HTTP and WebSocket ports to the emulator using adb:

adb reverse tcp:10002 tcp:10002
adb reverse tcp:10001 tcp:10001

Once forwarded, the app inside the emulator can use http://127.0.0.1:10002 as apiAddr and ws://127.0.0.1:10001 as wsAddr. Replace port numbers with the actual listening ports configured on your machine, and confirm that adb is connected to your target emulator before executing the commands. For production environments, use HTTPS and WSS endpoints, and verify DNS resolution, TLS certificates, firewalls, reverse proxies, and WebSocket upgrade handshakes on physical devices.

Prepare users and tokens

A userID uniquely identifies a user in OpenIM, while a token authenticates that user session. Your business backend is responsible for creating or binding users and issuing matching userID and token pairs to the Android client.

Before integrating OpenIMServer REST APIs into your backend service, refer to Preparation and Get a user token. The Android SDK login requires the following values:

FieldDescription
userIDThe OpenIM user ID of the signing-in user.
tokenThe authentication token corresponding to the user ID.
apiAddrThe OpenIMServer HTTP API URL.
wsAddrThe OpenIMServer WebSocket URL.

The userID must match the token subject; otherwise, authentication fails.

Prepare the Android project

Before integrating the SDK, verify that your Android project meets the following requirements:

  • Set minSdk to 21 or higher, enable Java 8 language desugaring/compilation options, and configure compileSdk to 36 or higher.
  • Declare android.permission.INTERNET in your AndroidManifest.xml and grant permissions to access network states.
  • Prepare a dedicated, persistent directory in private app storage (such as a subfolder in context.filesDir); never place SDK local SQLite databases in cache or shared external storage.
  • Ensure physical devices can resolve and connect to apiAddr, wsAddr, and media storage domains.
  • Verify that your app release packaging includes the native ABIs required by your target architectures.
  • Ensure your app gracefully handles lifecycle events, including network reconnection, foreground/background switching, token expiration, forced logout (kicked offline), and multi-device synchronization.

For dependency declarations and manifest configuration, see Integrate for Android. For SDK initialization and login flows, see Authenticate and manage a session.

Next steps

After completing your preparations, proceed to Authenticate and manage a session. After confirming that authentication succeeds and receiving the connection established callback (OnConnListener.onConnectSuccess), verify message delivery with Send your first message.