Skip to main content
This page describes core configuration, RUM configuration, remote configuration, privacy controls, Trace correlation, crash reporting, and symbol upload for the HarmonyOS SDK. All options come from the current ArkTS SDK public API.

Core configuration

Create core configuration with ConfigurationBuilder and pass it to Flashcat.initialize().
These three settings share their names and values with the Android, iOS and Flutter SDKs, so tuning advice transfers between platforms unchanged.
Flashcat.initialize() initializes a given instance name only once. A duplicate call returns the existing instance and does not re-register feature modules.

Reducing the impact of uploads on your own requests

If the app makes latency-sensitive requests of its own (sign-in, checkout, key provisioning) over a narrow uplink, SDK uploads can compete with them for the uplink. The symptom is a higher tail (P95) on your own request latency that comes and goes. Lower all three settings together to change how uploads are distributed over time — fewer uploads, spread further apart:
These three settings only change when uploads happen. They drop no events and remove no dimension from your dashboards, so if you do not want to sacrifice data, tune only these. BatchSize.LARGE has an extra benefit: larger batches compress better, so uplink bytes drop slightly.
Tuning advice transfers between platforms unchanged, because these three settings share names and values with the Android, iOS and Flutter SDKs. The one difference is that iOS batchProcessingLevel = .low is 5 batches per cycle, while HarmonyOS and Android use 1 — same direction, smaller reduction. See Android SDK performance impact and iOS SDK performance impact.
Several things that need to be turned off on other platforms cost nothing on HarmonyOS, and are neither configurable nor necessary: If the event volume itself is high, use event mapping with setEventMapper to drop specific noisy events (return null to drop). That is less invasive than changing your instrumentation. To comply with privacy regulations such as GDPR and CCPA, the SDK requires a tracking consent state at initialization, passed as the third argument of Flashcat.initialize(). You can change it at any time afterward.
With TrackingConsent.PENDING, the SDK writes events to a separate local buffer and sends nothing. When consent changes to GRANTED, the buffered data is migrated and uploaded automatically. Changing to NOT_GRANTED clears the buffer instead.
Every launch uses the value you pass to Flashcat.initialize. The SDK never overrides it with a previously stored state — the same contract as the Android and iOS SDKs. Your application is responsible for storing the user’s choice and passing it back at every initialization.
If your application initializes the SDK with a hard-coded value (for example GRANTED) on every launch, collection resumes after a restart even for a user who revoked consent. Call setTrackingConsent at the moment the user makes a choice, persist that choice yourself, and pass it to initialize on the next launch.
The consent state is also stored locally for exactly one purpose. The WorkSchedulerExtensionAbility that handles background upload runs in a separate process with no user and no access to the app’s decision. It reads the main process’s last recorded state. See Background and deferred upload. When consent is revoked (changed to NOT_GRANTED), the SDK clears the unsent pre-consent buffer and deletes batches already written to disk but not yet uploaded. Revoking consent also deletes the local view snapshot used for crash attribution. That snapshot is a whole view event — user id, name, email, and any custom context — so it is just as personal as a collected batch. At initialization:
After initialization, through the setTrackingConsent API (for example once the user responds to your privacy dialog):
Trace headers also honor tracking consent. The SDK injects correlatable traceparent and tracestate headers only when consent is GRANTED.

RUM configuration

Create RUM configuration with RumConfigurationBuilder and pass it to FlashcatRum.enable().
setTrackErrors(false) disables automatic error capture only. Crash reporting is unaffected: with the crash module enabled, uncaught exceptions still follow JsCrashPolicy — they are counted as crashes and reported as is_crash errors into the session that crashed (live under REPORT_AND_CONTINUE, replayed on the next launch under the exiting policies). Manual addError calls are the application’s explicit intent and are also still delivered. Use setEventMapper() if you need to filter those too.

Event mapping and redaction

Use setEventMapper() to perform lightweight processing before events are reported. Return the modified event to keep it, or null to drop it.
The event mapper runs on the SDK write path. Keep it fast, synchronous, and non-throwing. The SDK catches mapper errors and preserves the original event, but expensive logic increases client overhead.

Remote configuration

The session sample rate can be adjusted online in the console under Application Management → Remote Configuration, with no code change and no new release. The feature is off by default and has to be enabled at initialization:
Once enabled:
  • The SDK requests the configuration once at start-up and once whenever a new session begins. What it receives applies to the next new session; a session already running is unaffected, and the request never blocks session creation.
  • A sample rate crossing zero (from 0 to a non-zero rate, or the other way round) ends the current session immediately so the new rate redraws it — an emergency stop or restart does not have to wait for the session to rotate. Any other change waits for the next new session.
  • Fetched values are persisted locally, so the first session after a cold start is drawn under what was last published. When nothing has ever been fetched, or the console switched remote configuration off, the value set at initialization with setSessionSampleRate applies.
  • A request that fails, times out or comes back unreadable keeps the values already in force; nothing is wiped. The SDK retries twice shortly afterward, then waits for the next session or the next launch.
  • The HarmonyOS SDK reads only the session sample rate, Capture additional sessions on error (sessionOnError) and custom configuration keys; the other fields have no effect. There is no Session Replay, so the replay and Trace switches never appear for a HarmonyOS application.
  • On-error capture is the same switch as setSessionOnError at initialization: a value published from the console overrides the init value for the sessions drawn afterwards.
Sessions kept by on-error capture report a session sample rate of 0 and carry session.sampled_for_error: true; candidate sessions that never report an error are not uploaded and are not billed. See session_sampled_for_error in Data query syntax guide for how to filter them.
On a private deployment the configuration endpoint sits beside the RUM intake address at the /api/v2/rum/config path (if the intake address is https://host/api/v2/rum, the configuration endpoint is https://host/api/v2/rum/config). With setCustomEndpoint(), make sure your gateway lets that path through.
Custom configuration keys are read with GlobalRumMonitor.get().getRemoteConfig(), which returns a decoded object; it returns null when remote configuration is off, when the console has not set the field, or before a configuration has arrived:
Custom entries are delivered to clients and are readable by anyone holding the client token. Never put secrets, access tokens, or personally sensitive information in them.
The console-side fields, publishing, and activation are covered in Application Management · Remote Configuration.

Global attributes and user information

Global attributes are merged into the context object on subsequent events.
On sign-out, call clearAttributes() to drop the previous user’s business attributes and then stopSession(), so two users’ behavior never lands in the same session.
Set user information through the core instance. id, name, and email are written to the usr object on subsequent events.
setUserInfo() currently sets only id, name, and email. The server does not accept other user fields; use RUM global attributes or per-event attributes to write business dimensions to context.

Trace configuration

The Trace module generates W3C traceparent and tracestate, then correlates the generated trace id and span id to RUM resources through _dd.trace_id and _dd.span_id.
setFirstPartyHosts() is currently used only by the FlashcatHttp wrapper. The rcp interceptor itself is an explicit per-session opt-in, so requests made through a session with the interceptor receive Trace headers. If a request already has traceparent, the SDK does not overwrite the existing Trace context. Existing tracestate keeps other vendors and moves the updated dd= member to the front.

Crash reporting configuration

The Crash module provides two collection paths:
  • It listens to HarmonyOS hiAppEvent for APP_CRASH and APP_FREEZE, then reports system-replayed fault events through the RUM error pipeline on a later launch
  • It handles uncaught main-thread ArkTS exceptions live and uses JsCrashPolicy to report before the process exits or restarts
The default JS crash policy is REPORT_THEN_EXIT.
The default policy, REPORT_THEN_EXIT, exits the process after an uncaught ArkTS exception. To keep the application running, explicitly set JsCrashPolicy.REPORT_AND_CONTINUE (the crash still counts toward the crash rate) or JsCrashPolicy.OBSERVE_ONLY (not counted as a crash), and confirm that retaining a damaged process matches your business requirements.

REPORT_THEN_EXIT

This is the default policy. When an uncaught synchronous or asynchronous main-thread ArkTS exception occurs, the SDK synchronously persists a crash incident, flushes the current RUM writers, and exits the process. The incident is replayed into RUM on the next launch. If the synchronous write fails, the SDK attempts an asynchronous report and still exits.

REPORT_AND_RECOVER

The SDK synchronously persists the crash incident, checks the persisted crash-loop guard, then calls appRecovery.saveAppState() and restartApp(). The old process exits and a new process starts. The incident replayed on the next launch includes crash.recovered: true. The SDK falls back to exit behavior if any of these happens: recovery can’t be enabled, loop history can’t be persisted, the guard trips, the record can’t be marked recoverable, or the restart request fails.

REPORT_AND_CONTINUE

Requires SDK 0.7.2 or later. The SDK reports the exception as a crash (error.is_crash: true) into the live session, counts it in the view’s crash count, and leaves the process running. This policy does not exit or restart the process, persists no pending crash incident, and has nothing to replay on the next launch. This policy is not affected by setTrackErrors(false). The hiAppEvent.APP_CRASH that follows the same exception is not reported again. Use it when the application keeps the process alive on purpose (for example, next to another crash reporter’s JS crash protection) and these crashes must still count toward the crash rate. As with OBSERVE_ONLY, the uncaught exception may have left the application in a broken or inconsistent business state.

OBSERVE_ONLY

The SDK reports the exception asynchronously and leaves the current process running. This policy does not exit or restart the process. The event loop may remain responsive, but the uncaught exception may have left the application in a broken or inconsistent business state.

Crash-loop protection

Crash-loop protection affects only REPORT_AND_RECOVER. With the defaults, the first two crashes in a 60-second rolling window can restart the application. The third crash is reported synchronously but degrades to exit: the Nth crash in the window is blocked from restarting, allowing at most N-1 recovery restarts. Crash timestamps persist across processes, so restarting the application does not reset the guard. After the guard trips, each blocked crash becomes the newest timestamp. The application must remain crash-free for the full five-minute cooldown before history resets. Setting setCrashLoopThreshold(1) disables recovery restarts entirely: every crash is still reported synchronously, but each one exits and is never marked with crash.recovered.

Restore host application state

Automatic restart does not define which page state to restore. The host UIAbility must implement onSaveState, copy the required state into wantParam, and return ALL_AGREE:
The host application must read these parameters from the recovery Want and restore only state that is safe to resume. State restoration requires the host to implement onSaveState; the SDK triggers the state save and the restart when a crash occurs.

Capability boundary

Enable RUM and Crash early after Flashcat.initialize(). JS crash policy delivery does not depend on enable order: Crash pushes the policy to RUM, and RUM also pulls it on start, so enabling either module first activates the policy. Enabling FlashcatRum.enable() before FlashcatCrash.enable() is still recommended so pending crash incidents from the previous launch replay immediately. Crash events require the RUM pipeline for publication.

Background and deferred upload

By default, the SDK uploads on the foreground cadence configured by setUploadFrequency() and triggers flush() when the application backgrounds. If you want HarmonyOS WorkScheduler to wake the app for uploads, register deferred upload work.
The SDK registers the WorkScheduler task. The task is persisted (isPersisted, surviving reboots) and repeats on a 2-hour cycle.

Initializing inside the extension process

A WorkSchedulerExtensionAbility runs in a separate process and does not share the main process’s SDK instance. When it wakes, initialize with initializeForDeferredUpload before calling flushAndWait():
MyUploadExtensionAbility.ets
initializeForDeferredUpload differs from initialize in two important ways:
  • It takes no consent argument. The extension has no user in front of it, so it acts only on the main process’s last persisted decision. If nothing is persisted (the main application never initialized) or the stored decision is NOT_GRANTED, it reads, migrates, and uploads nothing.
  • It is read-only. It never writes back consent, device identity, or work registrations. HarmonyOS Preferences are per-process whole-file caches, so a write from the extension could clobber a revocation happening concurrently in the main process.
Do not call Flashcat.initialize() inside the extension process. It would overwrite the persisted consent state with the literal you pass, which can resume uploads after the user revoked consent. setTrackingConsent is also ignored in the extension process and logs an error.

Upload HarmonyOS crash symbols

To de-obfuscate ArkTS stacks and symbolicate native .so stacks in the console, upload build artifacts with @flashcatcloud/hvigor-plugin. The plugin uploads two artifact types: The plugin ships as an npm package (on npm, not ohpm). Declare it in hvigor/hvigor-config.json5 and let hvigor fetch it from npm:
hvigor/hvigor-config.json5
You can install it with npm instead. A HarmonyOS project root has no package.json, so npm install walks up the directory tree to find one. It then installs into whatever unrelated project it finds in a parent directory, often your home directory. Create one first:
Use 0.1.5 or later.
Then register the plugin in the module’s hvigorfile.ts:
hvigorfile.ts
On SaaS, omit endpoint — hvigor-plugin ≥ 0.1.3 defaults to https://ci.flashcat.cloud (not the RUM ingest host browser.flashcat.cloud). For a private deployment set FLASHCAT_SOURCEMAP_INTAKE_URL (scheme + host, no path; also requires ≥ 0.1.3), or pass endpoint: 'https://rum.example.com'. flashcatSymbolUploadPlugin() also accepts an optional buildDir. From 0.1.5, the build directory follows the product being built (-p product=beta → build/beta). Pass buildDir only when the artifacts are elsewhere.
After a release build, run the upload task as its own hvigor invocation:
Add --no-daemon when you configure the plugin from environment variables: the hvigor daemon does not re-read them. Otherwise the upload is silently skipped (FLASHCAT_API_KEY reads as unset) or uses a stale key (401), and the build still shows success. Values written directly into hvigorfile.ts are not affected.
Native symbolication depends on the GNU build-id in each .so. The HarmonyOS NDK generates build-id by default. If your build pipeline disables it, add -Wl,--build-id for the .so.