Core configuration
Create core configuration withConfigurationBuilder 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: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.
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.
Tracking consent
To comply with privacy regulations such as GDPR and CCPA, the SDK requires a tracking consent state at initialization, passed as the third argument ofFlashcat.initialize(). You can change it at any time afterward.
Consent states
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.The application owns the consent state
Every launch uses the value you pass toFlashcat.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.
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.
Setting and changing consent
At initialization:setTrackingConsent API (for example once the user responds to your privacy dialog):
RUM configuration
Create RUM configuration withRumConfigurationBuilder 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
UsesetEventMapper() to perform lightweight processing before events are reported. Return the modified event to keep it, or null to drop it.
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:- 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
setSessionSampleRateapplies. - 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
setSessionOnErrorat initialization: a value published from the console overrides the init value for the sessions drawn afterwards.
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.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:
Global attributes and user information
Global attributes are merged into thecontext 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.id, name, and email are written to the usr object on subsequent events.
Trace configuration
The Trace module generates W3Ctraceparent 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
hiAppEventforAPP_CRASHandAPP_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
JsCrashPolicyto report before the process exits or restarts
REPORT_THEN_EXIT.
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 onlyREPORT_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 hostUIAbility must implement onSaveState, copy the required state into wantParam, and return ALL_AGREE:
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
Background and deferred upload
By default, the SDK uploads on the foreground cadence configured bysetUploadFrequency() 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
AWorkSchedulerExtensionAbility 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.
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
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:
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.