Before you start

Before integrating unix-openim-sdk into a uni-app / uni-app x App, prepare an OpenIMServer reachable from the device, a trusted user-authentication flow, the UTS plugin, and a native build environment for every target platform. These prerequisites apply to both authenticating and managing a session and sending your first message. Web, H5, and Mini Program targets cannot use this native UTS plugin.

Prepare OpenIMServer

If you do not yet have an OpenIMServer deployment, follow the Docker deployment guide. Then verify that the actual Android, iPhone, or HarmonyOS device can reach apiAddr and wsAddr.

SDK initialization needs the following service addresses:

Do not verify the services only from the server or development Mac. A physical device cannot use the development computer's localhost; test LAN or public routing, TLS certificates, reverse-proxy rules, and WebSocket upgrades from the actual device.

A public client can connect to a public OpenIMServer. Signaling, session, translation, and other capabilities marked Commercial also require the matching commercial server capabilities. Do not use a public server's rejection to judge whether the commercial client API is implemented correctly.

Prepare the user and token

userID identifies an OpenIMSDK user, while the token authenticates that user. A trusted backend must create or bind OpenIMSDK users, issue tokens, and enforce application permissions. Never store an administrator token, secret, or other server credential in the App.

Before integrating your backend with the OpenIMServer REST API, see Prepare to use the Platform API and Issue a session token. If your product already has an account system, maintain a stable mapping between each application account and its OpenIMSDK userID, and ensure that the returned token belongs to that user.

We recommend exposing a session endpoint from your application backend so that the App receives only the minimum data required to sign in:

type OpenIMSDKSession = {
  userID : string
  token : string
}

async function loadOpenIMSDKSession() : Promise<OpenIMSDKSession> {
  const response = await uni.request({
    url: `${businessApiURL}/openim/session`,
    method: 'POST',
  })

  if (response.statusCode != 200) {
    throw new Error('Failed to load OpenIM SDK session')
  }

  return parseTrustedSessionResponse(response.data)
}

The application endpoint must authenticate the current application account before returning its OpenIMSDK sign-in details. It must not accept an arbitrary userID from the client and issue a token for that user without verification. apiAddr and wsAddr are normally controlled App-environment settings passed to initSDK(), rather than values changed in every user session response.

Prepare the UTS plugin and native runtime

Install the plugin at uni_modules/unix-openim-sdk, use the HBuilderX/uni-app 5.23 series, and prepare the native environment for each target:

• Android needs a compatible JDK and Android SDK, the plugin's declared AAR/Maven dependencies, and the ABI used by each target device.
• iOS needs compatible Xcode/CocoaPods. The final App must link, embed, and sign the plugin XCFrameworks correctly.
• HarmonyOS support is declared only for uni-app x with the commercial edition, the HAR matching the plugin contract, and an API 24 project.

The standard base does not contain these native dependencies. Build a custom base or use the project's local Android/iOS native workflow. Do not mix public and commercial native artifacts in one plugin directory, and do not read or modify the SDK database or native cache directly.

See Integrate by host and platform for lifecycle, type, and file-path differences.

Choose the platform identity

Pass an exported constant to initSDK().platformID instead of a numeric literal: OpenIMPlatformAndroid for Android, OpenIMPlatformIOS for iPhone, or OpenIMPlatformHarmony for HarmonyOS.

Initialization also requires a matching descriptive systemType, such as android, ios, or harmony. The platform constant and systemType participate in server-side multi-device policy and native runtime diagnostics, so they must identify the runtime that is actually executing the SDK.

Release checklist

Before releasing, test the environments and networks your product actually supports:

• initSDK() succeeds, login() succeeds, and onConnectSuccess is received.
• Foreground/background transitions, network interruption and recovery, token invalidation, and forced logout follow the product state machine.
• Android contains the required ABIs and has no duplicate classes or JNI libraries.
• The iOS device package links, embeds, and signs successfully, with complete usage descriptions and privacy manifests.
• HarmonyOS uses the exact commercial HAR required by the contract and reports platform-unsupported capabilities explicitly.
• Two different accounts can send and receive normal messages, query history, and keep state isolated after logout.
• Commercial APIs are tested against the corresponding commercial services.
• Logs, screenshots, and automation evidence contain no tokens, secrets, full private-message content, or unnecessary local absolute paths.

Continue the integration

After preparing these prerequisites, complete installation, initialization, and SDK inspection, then authenticate and manage the session. Once the connection succeeds, send your first message to a prepared user or group and verify the complete messaging flow.