This page describes the HarmonyOS SDK support scope and current limits so you can confirm whether your project meets the requirements before integration.
Support scope
| Item | Support |
|---|
| Project model | HarmonyOS NEXT / Stage model ArkTS projects |
| SDK form | HAR modules imported through @flashcatcloud/* packages |
| RUM data source | Events always write source: "harmony" |
| Device types | SDK HAR modules declare support for default, phone, tablet, 2in1, tv, wearable, and car |
| Runtime initialization | Initialize once in AbilityStage.onCreate when possible |
| Data upload | @kit.NetworkKit, POST /api/v2/rum |
Modules and capabilities
| Module | Package | Description |
|---|
| Core | @flashcatcloud/core | Initialization, configuration, context, user information, tracking consent, persistence, and upload |
| RUM | @flashcatcloud/rum | View, action, resource, error, and session handling |
| Trace | @flashcatcloud/trace | W3C traceparent / tracestate injection, RUM resource correlation, and the FlashcatHttp wrapper |
| Crash | @flashcatcloud/crash | APP_CRASH and APP_FREEZE collection, reported as RUM crash errors |
| Hvigor plugin | @flashcatcloud/hvigor-plugin | Uploads ArkTS sourcemap, nameCache.json, and native .so symbols |
Permission requirements
The host application must allow the SDK to access the network upload endpoint.
{
module: {
requestPermissions: [
{
name: "ohos.permission.INTERNET"
}
]
}
}
ohos.permission.GET_NETWORK_INFO. The current SDK event context does not automatically subscribe to network state changes, so this permission is not required for RUM upload.
Kit dependencies
The SDK source uses these HarmonyOS Kits:
| Kit | Usage |
|---|
@kit.AbilityKit | Application context, bundle information, exception observer, and foreground/background state |
@kit.BasicServicesKit | Device brand, model, OS version, API level, and device type |
@kit.NetworkKit | RUM batch upload and the FlashcatHttp request wrapper |
@kit.RemoteCommunicationKit | rcp interceptor for Trace header injection and resource recording |
@kit.ArkUI | routerPageUpdate observer for automatic views |
@kit.PerformanceAnalysisKit | hiAppEvent crash and hang observer, plus HiLog output |
@kit.BackgroundTasksKit | WorkScheduler deferred upload registration |
Initialization order
Enable the SDK in this order:
- Call
Flashcat.initialize(...) to create the core instance
- Call
FlashcatRum.enable(...) to enable RUM
- Call
FlashcatTrace.enable(...) to enable Trace
- Call
FlashcatCrash.enable(...) to enable Crash
Crash events are written through the RUM feature. Do not enable only @flashcatcloud/crash without RUM, because received crash replays will not produce RUM errors.
Supported automatic collection
| Capability | Support | Description |
|---|
| Automatic views | Supported | Requires setTrackNavigation(true) and FlashcatRum.startViewTracking(context) |
| Automatic taps | Supported through explicit wrapping | Requires setTrackUserInteractions(true) and FlashcatRum.trackTap(target) in click handlers |
| Automatic resources | Supported | Collected through the rcp interceptor or FlashcatHttp wrapper |
| Unhandled exceptions | Supported | Collected through errorManager.on('error') |
| Crashes and hangs | Supported | Replayed by hiAppEvent on the next launch |
| Trace correlation | Supported | Injects W3C traceparent and tracestate, and writes _dd.trace_id / _dd.span_id to RUM resources |
Current limits
| Limit | Description |
|---|
| Navigation scope | Automatic views currently listen to ArkUI routerPageUpdate; use manual views or additional wrapping for Navigation / NavDestination |
| Tap scope | The SDK does not automatically traverse every component; call FlashcatRum.trackTap() in button handlers or shared click wrappers |
| Network scope | Only requests using the rcp interceptor, FlashcatHttp, or manual resource APIs are collected |
| Resource lifecycle | A resource must finish while a view is active; in-flight resources are dropped when the view closes |
| Concurrent resources | A single view keeps at most 100 pending resources |
| rcp host restriction | setFirstPartyHosts() currently applies only to FlashcatHttp; an rcp session with the interceptor injects Trace headers into that session’s requests; requests that already have traceparent are not overwritten |
| Crash timing | HarmonyOS replays crashes and hangs on the next launch; the SDK does not synchronously report from the crashing process |
| Network status | connectivity.status is currently unknown |
| Session Replay | Not currently supported |
| Page performance metrics | HarmonyOS page rendering performance is not automatically collected |
| Frustration | setTrackFrustrations() is reserved and currently does not generate frustration events |
Symbolication compatibility
HarmonyOS crash stacks can contain both ArkTS / JS frames and native .so frames. The server resolves them as follows:
| Frame type | Resolution method | Required uploaded files |
|---|
| ArkTS / JS | Uses HarmonyOS sourceMaps.map to restore source files, function names, lines, and columns | sourceMaps.map; obfuscated builds can also include nameCache.json |
| Native C/C++ | Reuses the native symbolication pipeline and matches by build_id, architecture, and .so name | Unstripped .so files with GNU build-id |
Upload symbol files as part of your release build, and keep service and version aligned with SDK initialization and RUM events. Otherwise the console can receive crash events but cannot resolve frames back to source locations.
