OpenIMSDKDocs

Type at least two characters to search titles and routes.

EN

Language

ENEnglishEnglish docs简中简体中文中文文档
Browse SDKs · HarmonyOS
Platform
SDKsHarmonyOSEnterprise

Before you start

Prepare your OpenIMServer instance, user credentials, HarmonyOS development environment, and SDK HAR.

Copy

Before integrating the OpenIM HarmonyOS SDK, ensure you have an accessible OpenIMServer deployment, a valid userID and matching token, the commercially distributed SDK HAR, and a development environment configured to build HarmonyOS native modules.

Service endpoints

FieldDescription
apiAddrOpenIMServer HTTP API endpoint, such as https://api.example.com.
wsAddrOpenIMServer WebSocket endpoint, such as wss://ws.example.com.

Verify DNS resolution, TLS certificates, firewall rules, reverse proxy settings, and WebSocket upgrade handshakes directly on target physical phones, tablets, and 2in1 devices. Do not test these endpoints solely on your development workstation.

User credentials and token

Your business server must generate a userID and an authentication token, then provide both credentials to your HarmonyOS application for sign-in. For backend integration details, see API preparation and Get user token.

Development environment

  • DevEco Studio configured to build your target HarmonyOS application.
  • The HarmonyOS SDK matching your target device and API level, along with matching Hvigor and OHPM toolchains.
  • The commercially delivered OpenIM SDK HAR package.
  • An application module targeting phone, tablet, or 2in1.

Do not import multiple versions of the OpenIM HAR or manually extract and copy .so shared libraries into your project. Doing so causes duplicate native modules, ABI mismatches, or runtime errors between ArkTS declarations and compiled binaries.

Permissions and storage directories

The SDK requires ohos.permission.INTERNET. The SDK wrapper automatically monitors app foreground/background transitions and network connectivity changes; do not register redundant low-level lifecycle listeners or manual state APIs in application pages.

Configure persistent sandbox directories before initializing the SDK:

  • dataDir and dbPath store local SQLite databases and synchronized metadata.
  • logFilePath stores SDK execution logs.
  • All paths must point to stable, writable locations within the application's internal files directory. Do not use temporary cache directories or shared external paths.

Pre-flight checklist

  • Verify that the HAR package contains the required ABI architectures (arm64-v8a, x86_64) for your target devices.
  • Confirm physical devices can reach the API, WebSocket, and media object storage domains.
  • Ensure the userID matches the subject in the token before attempting sign-in.
  • Implement token expiration handling, account switching logic, and multi-device kick-out events, and verify that synchronization resumes smoothly when the app returns to the foreground or network connectivity recovers.
  • Treat logging out and process-level SDK termination as separate phases. Do not destroy the SDK instance when unmounting individual pages or closing single windows.

Next, proceed to Environment-specific implementation.