OpenIM SDK for uni-app / uni-app x

OpenIM unix-openim-sdk is a native UTS plugin that provides user, friend, conversation, group, message, event, and local-database capabilities to uni-app and uni-app x Apps. The plugin owns the only OpenIM Core in the host process. Import flat functions from @/uni_modules/unix-openim-sdk; do not create an SDK instance.

Supported environments

Use the HBuilderX/uni-app 5.23 series. Android and iOS require a custom base or local native project containing the plugin's native dependencies; the standard base cannot load them.

Public and commercial capabilities

This documentation covers both public capabilities and commercial extensions. APIs, events, and fields carrying a Commercial badge require the commercial unix-openim-sdk and a matching OpenIMServer deployment. Edition and platform support are separate: a public API can still return platform-unsupported on a particular platform.

Commercial extensions include signaling, SDK session snapshots, translation, and selected message or conversation features. onSDKSessionChanged is synthesized by the plugin from initialization, login, logout, token, and account transitions. It is not a native OpenIM Core event.

Integration sequence

1. Install unix-openim-sdk and prepare a custom base or local native project.
2. Call initSDK() with apiAddr, wsAddr, platform, logging, and systemType.
3. Save the subscription handles returned by connection, message, and business event listeners.
4. Obtain the current user's userID and token from a trusted backend, then call login(userID, token).
5. Wait for onConnectSuccess, load snapshots, and apply subsequent events incrementally.
6. On sign-out, call logout() and release listeners with off(subscription). Call unInitSDK() only when the App no longer uses the SDK.

Invocation model

Promises resolve directly to business values; there is no Web SDK { data } wrapper. Event registration synchronously returns an OpenIMSDKEventSubscription:

import { off, onRecvNewMessage } from '@/uni_modules/unix-openim-sdk'

const messageSubscription = onRecvNewMessage((message) => {
  console.log(message.clientMsgID)
})

off(messageSubscription)

Do not use offAll() for normal scoped cleanup. It removes every listener owned by the plugin instance and is intended only for full App teardown or controlled test reset.

Security boundaries

• Obtain user tokens from a trusted backend. Never embed administrator tokens, secrets, or fixed user tokens in the App.
• Physical devices must use reachable apiAddr and wsAddr values; localhost points to the device itself.
• Do not open, move, or modify the SDK-managed database directly.
• Redact tokens, full private-message bodies, and commercial credentials from logs and reports.
• AV Runtime is a separate UTS plugin. It reuses this plugin's single login session but is not part of the public IM API.

Continue with Before you start, Install, initialize, and inspect the SDK, and Event overview.