核心配置
核心配置通过ConfigurationBuilder 创建,并传给 Flashcat.initialize()。
这三个参数与 Android、iOS、Flutter SDK 同名同值,调优结论可以跨平台直接套用。
Flashcat.initialize() 同一个实例名只会初始化一次。重复初始化会返回已存在实例,不会重新注册功能模块。降低上传对业务请求的影响
如果应用自身有延迟敏感的网络请求(如登录、下单、密钥申请),并且运行在上行带宽较窄的网络上,SDK 的上传可能与业务请求争抢上行链路,表现为业务请求耗时的长尾(P95)升高,且时好时坏。 这种情况下把上面三个参数一起下调,改变的是上传的时间分布——上传次数更少、单次更分散:调优结论可跨平台套用,仅 iOS 的
batchProcessingLevel = .low 为 5 批次/周期(HarmonyOS 与 Android 为 1),方向一致、降幅略小。参见 Android SDK 性能影响 与 iOS SDK 性能影响。
如果事件量本身偏大,可以用 事件过滤 的
setEventMapper 丢弃指定的噪音事件(返回 null 即丢弃),侵入性小于改业务打点代码。
用户跟踪同意
为遵守 GDPR、CCPA 等隐私法规,SDK 要求在初始化时设置用户跟踪同意状态(Flashcat.initialize() 的第三个参数),并可在初始化后随时变更。
同意状态说明
如果初始化时使用
TrackingConsent.PENDING,SDK 会将事件写入单独的本地缓冲区,但在同意状态更改为 GRANTED 之前不会发送;变更为 GRANTED 后缓冲数据自动迁移并上传,变更为 NOT_GRANTED 则清空缓冲。应用是同意状态的唯一权威
每次启动都以您传给Flashcat.initialize 的值为准。 SDK 不会用历史状态覆盖它——这一点与 Android、iOS SDK 完全一致。您的应用负责保存用户的选择,并在每次初始化时传回给 SDK。
同意状态同时会被持久化到本地,但只服务于一个用途:后台上传使用的 WorkSchedulerExtensionAbility 是独立进程,它面前没有用户、也拿不到应用的判断,只能读取主进程最后一次记录的决定。详见后台和延迟上传。
撤销授权时(变更为 NOT_GRANTED),SDK 不仅清空未发送的 pre-consent 缓冲区,还会删除已经落盘、尚未上传的批次。
撤销授权还会删除用于崩溃归因的本地 view 快照。该快照是一份完整的 view 事件,包含用户 ID、姓名、邮箱和自定义上下文,与已采集批次同样敏感。
设置与更改同意状态
初始化时设置:setTrackingConsent API 更改(例如用户在隐私弹窗中做出选择后):
RUM 配置
RUM 配置通过RumConfigurationBuilder 创建,并传给 FlashcatRum.enable()。
setTrackErrors(false) 只关闭自动错误采集。崩溃不受影响:启用 Crash 模块后,未捕获异常仍按 JsCrashPolicy 计入崩溃并以 is_crash error 上报到崩溃发生的那个会话(REPORT_AND_CONTINUE 当场上报,退出类策略在下次启动时回放);手动调用的 addError 属于应用的显式意图,同样照常上报。如需连这两类一起过滤,请使用 setEventMapper()。事件过滤和脱敏
setEventMapper() 可以在事件上报前做轻量处理。返回修改后的事件表示继续上报,返回 null 表示丢弃事件。
远程配置
会话采样率可以在控制台 应用管理 → 远程配置 页签在线调整,无需改代码、重新发版。该功能默认关闭,需要在初始化时开启:- SDK 在启动时与每次新建会话时各请求一次配置,拿到的配置对下一个新会话生效,进行中的会话不受影响;请求不会阻塞会话创建。
- 采样率跨过 0(由 0 调为非 0,或由非 0 调为 0)时当前会话会立即结束,由新配置重新抽样,紧急关停或重新开启不必等会话自然轮换;其余变化都等到下一个新会话。
- 下发的值会持久化到本地,冷启动后的第一个会话即按上次下发的配置抽样;从未成功拿到过配置、或控制台停用了远程配置时,恢复使用初始化时的
setSessionSampleRate。 - 请求失败、超时或响应无法识别时,沿用已生效的值,不会清空;SDK 会短暂重试两次,之后等到下一个新会话或下次启动才再请求。
- HarmonyOS SDK 只读取会话采样率、错误会话补充采集(
sessionOnError)与自定义配置项三项,其余配置项不生效。没有 Session Replay,回放与 Trace 相关的开关不会在 HarmonyOS 应用里出现。 - 异常补采与初始化时的
setSessionOnError是同一个开关:控制台下发的值覆盖初始化值,对之后抽样的会话生效。
0,并带 session.sampled_for_error: true 标记;没有报错的候选会话不会上传、不产生费用。筛选方式见数据查询语法指南中的 session_sampled_for_error。
私有化部署时配置接口位于 RUM 上报地址旁的
/api/v2/rum/config 路径(如上报地址是 https://host/api/v2/rum,配置接口就是 https://host/api/v2/rum/config)。使用 setCustomEndpoint() 时,请确认网关放行了该路径。GlobalRumMonitor.get().getRemoteConfig() 读取,返回已解析好的对象;未开启远程配置、控制台未设置该项,或尚未拿到配置时返回 null:
全局属性和用户信息
全局属性会合并到后续事件的context 对象中。
用户退出登录时,建议先
clearAttributes() 清掉上一位用户的业务属性,再 stopSession() 结束会话,避免两位用户的行为落在同一个会话里。id、name 和 email 会写入后续事件的 usr 对象。
Trace 配置
Trace 模块负责生成 W3Ctraceparent 和 tracestate,并把生成的 trace id 和 span id 关联到 RUM resource 的 _dd.trace_id 和 _dd.span_id 字段。
当前
setFirstPartyHosts() 只由 FlashcatHttp 包装器使用。rcp 拦截器本身就是每个 session 的显式接入点,因此添加拦截器的 session 会对其请求注入 Trace header。请求已带有 traceparent 时,SDK 不会覆盖已有 Trace 上下文;已有 tracestate 会保留其他 vendor,并把更新后的 dd= 成员放在最前。崩溃采集配置
Crash 模块提供两条采集路径:- 通过 HarmonyOS
hiAppEvent监听APP_CRASH和APP_FREEZE,在后续启动时通过 RUM error 管道上报系统回放的故障事件 - 实时处理主线程上未捕获的 ArkTS 异常,根据
JsCrashPolicy在进程退出或重启前完成上报
REPORT_THEN_EXIT。
REPORT_THEN_EXIT
这是默认策略。发生主线程上未捕获的同步或异步 ArkTS 异常时,SDK 会同步持久化崩溃记录、刷新当前 RUM 写入器,然后退出进程。记录会在下一次启动时回放到 RUM。如果同步写入失败,SDK 会尝试异步上报并仍然退出。
REPORT_AND_RECOVER
SDK 会同步持久化崩溃记录,检查持久化的崩溃循环保护,然后调用 appRecovery.saveAppState() 和 restartApp()。旧进程退出并启动新进程,下一次启动回放的记录会带有 crash.recovered: true。
如果无法启用恢复、无法持久化循环记录、保护被触发、无法把记录标记为可恢复,或重启请求失败,SDK 会降级为退出。
REPORT_AND_CONTINUE
需要 SDK 0.7.2 及以上。SDK 会把异常作为崩溃(error.is_crash: true)实时上报到当前会话,计入该 view 的崩溃数,然后让进程继续运行。该策略不会退出或重启进程,也不写入待处理崩溃记录,下次启动不会回放。
该策略不受 setTrackErrors(false) 影响。同一次异常随后产生的 hiAppEvent.APP_CRASH 不会重复上报。
当应用有意保持进程存活(例如同时接入了其他崩溃上报工具的 JS 崩溃保护),又需要这类崩溃计入崩溃率时,使用该策略。与 OBSERVE_ONLY 一样,未捕获异常可能已经使应用处于损坏或不一致的业务状态。
OBSERVE_ONLY
SDK 会异步上报异常并让当前进程继续运行。该策略不会退出或重启进程。事件循环可能仍能响应,但未捕获异常可能已经使应用处于损坏或不一致的业务状态。
崩溃循环保护
循环保护仅影响REPORT_AND_RECOVER。默认配置下,60 秒滚动窗口内前两次崩溃可以重启,第三次崩溃会同步上报但降级为退出,即窗口内第 N 次崩溃禁止重启,最多允许 N-1 次恢复重启。
崩溃时间戳会跨进程持久化,应用重启不会重置保护。保护触发后,每次被阻止的崩溃都会成为最新时间戳;应用需要保持完整的 5 分钟无崩溃冷却期,记录才会重置。将 setCrashLoopThreshold(1) 设为 1 会完全禁用恢复重启:每次崩溃仍同步上报,但都会退出,也不会标记 crash.recovered。
恢复宿主应用状态
自动重启不会自行定义需要恢复的页面状态。宿主UIAbility 需要实现 onSaveState,把需要的状态写入 wantParam,并返回 ALL_AGREE:
Want 中读取这些参数,并且只恢复可以安全继续的状态。状态恢复依赖宿主实现 onSaveState,SDK 负责在崩溃时触发状态保存和重启。
能力边界
后台和延迟上传
SDK 默认在前台按setUploadFrequency() 的间隔上传,并在应用进入后台时触发 flush()。如果需要由 HarmonyOS WorkScheduler 唤醒上传,可以注册延迟上传任务。
SDK 负责注册 WorkScheduler 任务。任务是持久化的(
isPersisted,跨重启存活),按 2 小时周期唤醒。
在扩展进程中初始化
WorkSchedulerExtensionAbility 是独立进程,不共享主进程的 SDK 实例。被唤醒后必须先用 initializeForDeferredUpload 初始化,再调用 flushAndWait():
MyUploadExtensionAbility.ets
initializeForDeferredUpload 与 initialize 有两点关键差别:
- 不接收同意状态参数。 扩展进程面前没有用户,只能依据主进程最后一次持久化的决定行事;没有持久化记录(主进程从未初始化过)或记录为
NOT_GRANTED时,它不读取、不迁移、也不上传任何数据。 - 只读。 它不会写回同意状态、设备标识或任务注册信息。HarmonyOS Preferences 是按进程的整文件缓存,扩展进程的写入可能覆盖主进程正在进行的撤销操作。
上传 HarmonyOS 崩溃符号
如需在控制台还原混淆后的 ArkTS 栈和 Native.so 栈,请使用 @flashcatcloud/hvigor-plugin 上传构建产物。
该插件会上传两类文件:
该插件以 npm 包发布(在 npm,不在 ohpm)。推荐在
hvigor/hvigor-config.json5 中声明,由 hvigor 自行从 npm 拉取:
hvigor/hvigor-config.json5
package.json,而 npm install 会逐级向上查找,最终把依赖装进父目录里某个无关工程(常见是用户主目录),所以要先创建一个:
hvigorfile.ts 中注册插件:
hvigorfile.ts
公有云省略
endpoint 时,hvigor-plugin ≥ 0.1.3 默认上传到 https://ci.flashcat.cloud(不是 RUM 上报用的 browser.flashcat.cloud)。私有化部署请设置环境变量 FLASHCAT_SOURCEMAP_INTAKE_URL(协议 + 域名,不带路径;同样需要 ≥ 0.1.3),或传 endpoint: 'https://rum.example.com'。flashcatSymbolUploadPlugin() 还接受可选参数 buildDir。0.1.5 起产物目录会自动跟随构建的 product(-p product=beta → build/beta),只有产物不在该位置时才需要传 buildDir。