[RFC]:

Bắt đầu bằng việc xem xét các triển khai SDK iOS và Android hiện có, open-im-sdk-core và cấu trúc mô-đun RNOH được đề xuất trong harmony/. Sau đó, đánh giá các yêu cầu về ArkTS, NAPI, biên dịch chéo Go, build và kiểm thử. Công việc được xem là hoàn tất khi HarmonyOS cung cấp JavaScript API hiện có, hỗ trợ các tính năng core và nền tảng được liệt kê, vượt qua các bài kiểm thử đơn vị và tích hợp, đồng thời có tài liệu thiết lập và một ứng dụng mẫu.

Proposal: HarmonyOS (OpenHarmony) Support for open-im-sdk-reactnativeProposal OverviewThis proposal requests adding HarmonyOS (OpenHarmony) platform support to open-im-sdk-reactnative, enabling developers to build cross-platform applications targeting iOS, Android, and HarmonyOS from a single React Native codebase. The goal is to expand OpenIM's reach into the rapidly growing HarmonyOS ecosystem and maintain OpenIM's position as a leading open-source IM solution for mobile platforms.MotivationHarmonyOS has emerged as a significant mobile operating system, particularly in the Chinese market, with hundreds of millions of devices in active use. As of 2024-2025, HarmonyOS NEXT (the pure HarmonyOS without Android compatibility) has been officially released, and major Chinese enterprises are required or strongly encouraged to provide HarmonyOS-native versions of their applications.The React Native community has responded with RNOH (React Native OpenHarmony), an officially-maintained port by Huawei that enables React Native applications to run on HarmonyOS. This has created an opportunity—and a need—for cross-platform SDKs to extend their support.Current pain points for developers building enterprise apps:
No official HarmonyOS support in OpenIM React Native SDK. Teams targeting all three platforms (iOS/Android/HarmonyOS) must either:

Drop HarmonyOS support entirely (not viable for enterprise clients in China)
Implement a separate IM solution for HarmonyOS using a different SDK (e.g., JiGuang, RongCloud, Easemob), breaking the unified architecture
Manually bridge OpenIM's core protocol via custom TurboModules, which is costly and hard to maintain

Fragmentation risk for OpenIM users. Without HarmonyOS support, OpenIM risks losing enterprise adoption in markets where HarmonyOS is mandatory, pushing developers toward proprietary competitors that already offer HarmonyOS SDKs.

Inconsistency with OpenIM's open-source mission. As an open-source IM solution, OpenIM should ideally support all major mobile platforms to remain a viable alternative to commercial offerings.
Real-world use case: We are currently building an enterprise OA (Office Automation) application similar to DingTalk, requiring simultaneous support for iOS, Android, and HarmonyOS. OpenIM is our preferred IM solution, but the lack of HarmonyOS support forces us to either delay HarmonyOS rollout by 1-2 iterations or adopt a different SDK for HarmonyOS—both of which compromise our architecture.Detailed DesignWe propose adding HarmonyOS support to open-im-sdk-reactnative by leveraging the RNOH framework and OpenIM's existing core SDK.Architecture┌─────────────────────────────────────────────────┐
│ open-im-sdk-reactnative (JS layer) │
│ Unified API across all platforms │
└──────┬──────────┬───────────────┬───────────────┘
│ │ │
▼ ▼ ▼
┌──────┐ ┌─────────┐ ┌───────────────┐
│ iOS │ │ Android │ │ HarmonyOS │
│ │ │ │ │ (new) │
│ │ │ │ │ RNOH Module │
└──┬───┘ └────┬────┘ └───────┬───────┘
│ │ │
└───────────┴────────────────┘
│
▼
┌──────────────────┐
│ open-im-sdk-core │
│ (Go core) │
└──────────────────┘Implementation StepsPhase 1: Foundation (Estimated 2-3 weeks)
Create a new harmony/ directory in the SDK structure, following RNOH's module conventions.
Implement a TurboModule (OpenIMSDKModule) in ArkTS that bridges the existing JS API to the native HarmonyOS layer.
Set up the build configuration (oh-package.json5, CMakeLists for native bindings).
Phase 2: Core Functionality (Estimated 4-6 weeks)
Integrate open-im-sdk-core (Go SDK):

Compile the Go core to a HarmonyOS-compatible binary (.so for ARM64).
Bridge Go ↔ ArkTS using HarmonyOS's NAPI (Native API).

Implement core APIs (matching iOS/Android signatures):

SDK initialization (initSDK)
Authentication (login, logout)
Message sending (text, image, voice, video, file)
Conversation management
Group operations
User profile operations

Event listeners: Bridge native callbacks to JS via RCTEventEmitter equivalent in RNOH.
Phase 3: Platform-Specific Features (Estimated 2-3 weeks)
HarmonyOS-specific integrations:

Push notifications via HMS Push Kit
File storage using HarmonyOS file access APIs
Background task handling

Permission management aligned with HarmonyOS's permission model.
Phase 4: Testing & Documentation (Estimated 2 weeks)
Unit tests for the HarmonyOS module.
Integration tests against a live OpenIM server.
Documentation: setup guide, API reference, sample app.
Code Snippet ExampleA minimal HarmonyOS TurboModule structure (ArkTS):typescript// harmony/openimsdk/src/main/ets/OpenIMSDKTurboModule.ts
import { TurboModule, TurboModuleContext } from '@rnoh/react-native-openharmony/ts';
import { OpenIMSDKCore } from './native/OpenIMSDKCore'; // Bridges to Go core

export class OpenIMSDKTurboModule extends TurboModule {
private core: OpenIMSDKCore;

constructor(ctx: TurboModuleContext) {
super(ctx);
this.core = new OpenIMSDKCore();
}

async initSDK(config: { apiAddr: string; wsAddr: string }): Promise {
return await this.core.init(config.apiAddr, config.wsAddr);
}

async login(userID: string, token: string): Promise {
await this.core.login(userID, token);
}

async sendMessage(message: string, conversationID: string): Promise {
return await this.core.sendMessage(message, conversationID);
}

// ... other methods matching the iOS/Android API surface
}API CompatibilityThe HarmonyOS implementation will expose the exact same JavaScript API as the existing iOS/Android SDK, ensuring zero changes to application code:typescript// This code works on iOS, Android, AND HarmonyOS without modification
import OpenIMSDK from 'open-im-sdk-reactnative';

await OpenIMSDK.initSDK({ apiAddr, wsAddr });
await OpenIMSDK.login({ userID, token });
await OpenIMSDK.sendMessage(textMessage, conversationID);Alternatives ConsideredSeveral alternatives were evaluated before settling on this proposal:1. Use a different IM SDK for HarmonyOS (e.g., JiGuang, RongCloud)Rejected because:

Forces a dual-SDK architecture, doubling maintenance burden.
Requires running two backend IM services (or paying for a commercial one).
Breaks the unified message protocol and history—messages sent from HarmonyOS users would not be in the OpenIM server.
Defeats the purpose of choosing an open-source solution.
2. Bridge OpenIM's WebSocket protocol manually in user applicationsRejected because:

Each user team would have to reimplement protocol handling, message encoding, retry logic, etc.
High risk of bugs and inconsistencies.
No reuse of OpenIM's mature SDK core (offline message sync, conversation management, etc.).
Effectively duplicates work the SDK is meant to abstract.
3. Wait for community contributionRejected because:

HarmonyOS integration requires deep knowledge of both OpenIM's core architecture and RNOH—a niche skillset.
Without official commitment, the integration may never reach production quality.
Enterprise users cannot adopt unofficial forks for compliance/security reasons.
4. Use OpenIM's Web SDK (open-im-sdk-js) inside a WebView on HarmonyOSRejected because:

Significant performance degradation, especially for media messages.
Loses native push notification capability.
Poor UX compared to a true native integration.
Not viable for production enterprise apps.
Why the proposed approach is preferred: It maintains API consistency across all platforms, leverages OpenIM's existing battle-tested core, and provides a sustainable long-term solution maintained by the OpenIM team alongside the iOS/Android implementations.ImpactPositive Impact
Expanded market reach: OpenIM becomes viable for the rapidly growing HarmonyOS ecosystem, particularly important for enterprise customers in China.
Architectural consistency: Cross-platform teams maintain a single, unified IM architecture instead of fragmenting across SDKs.
Competitive positioning: OpenIM matches or exceeds the platform coverage of commercial competitors like JiGuang and RongCloud.
Community growth: Attracts contributors and users from the HarmonyOS community.
Considerations
Maintenance overhead: Adds a third platform to the SDK's CI/CD, testing, and release process. This is the primary cost.
Build complexity: Requires Go cross-compilation for HarmonyOS ARM64 and integration with RNOH's build system.
Dependency on RNOH stability: RNOH is still evolving; SDK behavior may need adjustments as RNOH matures.
Backward CompatibilityThis proposal is fully backward-compatible. No changes are required for existing iOS/Android users. The HarmonyOS support is purely additive.Migration Path for Existing UsersExisting applications can opt in to HarmonyOS support by:

Upgrading to the new SDK version.
Adding HarmonyOS platform configuration to their RNOH project.
No JavaScript code changes required.
Additional InformationRelated Projects and References
RNOH (React Native OpenHarmony): https://gitee.com/openharmony-sig/ohos_react_native — Huawei-maintained official port of React Native to HarmonyOS, currently supporting both legacy and Fabric architectures.
OpenIM Core SDK: https://github.com/openimsdk/openim-sdk-core — Go-based core SDK that powers iOS/Android implementations and could be reused for HarmonyOS.
HarmonyOS Developer Documentation: https://developer.harmonyos.com/ — Official docs for ArkTS, NAPI, and HarmonyOS app development.
Related Discussions
(Please link any prior issues, RFC discussions, or community threads related to HarmonyOS support here.)
Willingness to ContributeWe are willing to contribute to this effort in the following ways:

Detailed technical design review
Implementation contributions (architecture, code)
Testing on real HarmonyOS devices
Documentation and example apps
Bug reports and feedback during beta phase
We hope the OpenIM team will consider this proposal and look forward to discussing implementation details, timeline, and how the community can support this initiative.