@cloudcare/hvigor-ohos-plugin 0.1.0 → 0.1.2-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.1.2-alpha.1] - 2026-10-19
+
+- Added automatic Session Replay integration for supported ArkUI `@Entry` pages, ArkWeb components and touch events, without manual page registration or event forwarding. Requires `@guancecloud/ft_session_replay` in the HAP and Replay initialization; touch coordinates require `TouchPrivacy.SHOW`.
+- Added automatic recording of Router page-switch animations for Session Replay, including slide and fade effects. Default system animations may differ during playback.
+- Fixed build/runtime errors and missing log arguments when automatic console/HiLog collection is enabled.
+- Fixed cold-launch instrumentation for inherited UIAbilities and InsightIntent entries, preserving existing lifecycle callbacks. Apps without an AbilityStage now use approximate application-initialization timing.
+- Fixed build errors and repeated execution of page `.id()` expressions caused by automatic Replay collection.
+- Changed automatic collection to run only in modules that declare the required SDK packages in their own `oh-package.json5` `dependencies`; other modules are left unchanged.
+- Fixed automatic logging, cold-launch or Replay code being omitted from some application modules when multiple HAP modules are built together.
+
+## [0.1.1] - 2026-09-14
+
+- Fixed console/HiLog instrumentation being skipped when cold-launch instrumentation is enabled in the same Hvigor plugin.
+
 ## [0.1.0] - 2026-09-14
 
 - Added compiler instrumentation for automatic console/HiLog collection.
@@ -17,5 +31,3 @@
 ## [0.1.0-alpha.1] - 2026-09-11
 
 - Prepared the initial npm prerelease of the console/HiLog and cold-launch instrumentation plugin.
-
-

package/README.md

@@ -1,27 +1,19 @@
 # Guance HarmonyOS Hvigor Plugin
 
-[![Hvigor plugin version](https://img.shields.io/badge/dynamic/json?label=plugin&color=orange&query=%24.version&uri=https%3A%2F%2Fraw.githubusercontent.com%2FGuanceCloud%2Fdatakit-harmonyos%2Fmaster%2Fft_hvigor_plugin%2Fpackage.json)](https://github.com/GuanceCloud/datakit-harmonyos/tree/master/ft_hvigor_plugin)
+[![Hvigor plugin version](https://img.shields.io/badge/dynamic/json?label=plugin&color=orange&query=$.version&uri=https://static.guance.com/ft-sdk-package/badge/harmonyos/plugin/version.json)](https://www.npmjs.com/package/@cloudcare/hvigor-ohos-plugin)
 
-`@cloudcare/hvigor-ohos-plugin` is the build-time companion for `@guancecloud/ft_sdk`. It instruments direct `console.*` and `hilog.*` calls and injects cold-launch lifecycle tracking into a HAP module's `src/main/ets` sources. Runtime log collection remains controlled by `FTLoggerConfig.setEnableConsoleLog(true)` in `@guancecloud/ft_sdk`.
+`@cloudcare/hvigor-ohos-plugin` adds automatic console/HiLog collection, cold-launch tracking, and Session Replay support for eligible ArkUI `@Entry` pages. Application files are not modified on disk.
 
-## Install
-
-This is a Hvigor tool package, so declare it in the project-level `hvigor/hvigor-config.json5` rather than a module `oh-package.json5`:
+The plugin adds build-time instrumentation but does not enable collection by itself. Enable console/HiLog collection with `FTLoggerConfig.setEnableConsoleLog(true)`. To use Session Replay, declare `@guancecloud/ft_session_replay` and initialize `FTSessionReplay` after the core SDK and RUM; the plugin then connects supported page visibility, touch, Router transition, and ArkWeb events to Replay automatically.
 
-```json5
-{
-  "dependencies": {
-    "@cloudcare/hvigor-ohos-plugin": "0.1.0"
-  }
-}
-```
+## Install
 
-For local development, a filesystem dependency is also supported:
+This is a Hvigor tool package, so declare it in the project-level `hvigor/hvigor-config.json5` rather than a module `oh-package.json5`. Replace `<latest-version>` with the latest published version that supports the features you use, including a prerelease when needed:
 
 ```json5
 {
   "dependencies": {
-    "@cloudcare/hvigor-ohos-plugin": "file:../ft_hvigor_plugin"
+    "@cloudcare/hvigor-ohos-plugin": "latest"
   }
 }
 ```
@@ -38,10 +30,33 @@ export default {
 }
 ```
 
-The plugin preserves the original console/HiLog output and does not modify application files on disk. It injects its installed package version into the SDK's `sdk_pkg_info.track` tag at build time, so rebuilding after a plugin upgrade reports the matching version. It injects cold-launch application initialization into Ability `onCreate()` methods, first-UIAbility creation into `UIAbility.onCreate()`, and first-frame observation into `UIAbility.onWindowStageCreate()`. Do not add manual cold-launch timing calls to application code.
+The plugin preserves the original console/HiLog output, reports its installed version through `sdk_pkg_info.track`, and collects cold-launch timing automatically. Do not add manual cold-launch timing calls to application code.
+
+Configure an `AbilityStage` as the HAP module's `srcEntry` for accurate application-initialization timing. Without an `AbilityStage`, initialization timing is approximate.
+
+## Automatic Session Replay
+
+When the HAP declares `@guancecloud/ft_session_replay`, the plugin automatically registers supported `@Entry` pages and tracks their visibility. Existing root IDs and callbacks are preserved. Session Replay collection is not enabled when the Replay package is absent.
+
+When both `@guancecloud/ft_sdk` and `@guancecloud/ft_session_replay` are declared, the plugin automatically associates ArkUI `Web` components with their controllers so supported ArkWeb content is linked to the correct Replay page. No manual Web component ID or controller registration is required.
+
+Replay initialization, sampling, privacy settings, and page-change notifications are documented in the `@guancecloud/ft_session_replay` README.
+
+The plugin automatically captures page touch events without changing existing `onTouch` behavior. Touch coordinates are recorded only when `TouchPrivacy.SHOW` is configured.
+
+Router page changes and explicit `PageTransitionEnter/Exit` slide and opacity animations are captured automatically. Existing transition callbacks are preserved; playback of default system transitions may be approximate.
 
 ## Compatibility
 
-Version `0.1.0` is verified with Node.js 18 or newer, Hvigor and `@ohos/hvigor-ohos-plugin` 6.23.5, and HarmonyOS SDK 6.0.2 (API 22). It supports `@guancecloud/ft_sdk` `0.1.17` and later releases.
+The plugin is verified with Node.js 18 or newer, Hvigor and `@ohos/hvigor-ohos-plugin` 6.23.5, and HarmonyOS SDK 6.0.2 (API 22). Console/HiLog and cold-launch instrumentation require `@guancecloud/ft_sdk` `0.1.17` or later. Automatic Session Replay additionally requires `@guancecloud/ft_sdk` `0.1.18` or later and `@guancecloud/ft_session_replay` `0.1.0` or later.
+
+`@ohos/hvigor-ohos-plugin` is supplied by DevEco Studio's Hvigor runtime.
+
+Each module that needs automatic collection must declare these SDK packages under `dependencies` in its own `oh-package.json5`:
+
+- `@guancecloud/ft_sdk`: required for console/HiLog and cold-launch collection.
+- `@guancecloud/ft_session_replay`: additionally required for Session Replay.
+
+The plugin checks SDK dependencies in the `oh-package.json5` of the module that contains each source file (HAP, HAR or HSP). Declaring an SDK only in the project-root `oh-package.json5`, another module, or `devDependencies` does not enable automatic collection for that source file.
 
-`@ohos/hvigor-ohos-plugin` is supplied by DevEco Studio's Hvigor runtime. `@guancecloud/ft_sdk` must still be declared as the application's runtime HAR dependency because the generated imports target that package.
+Optional logging calls such as `console?.info(...)` and `hilog.info?.(...)` are not automatically collected.