HarmonyOS App Integration¶

By collecting metrics data from HarmonyOS apps, you can analyze app performance visually.

Reading Path¶

First-time integration: start with Quick Start
Full integration: continue reading this article
Legacy package name migration: see Legacy Configuration Migration
HAR package download: see How to Obtain HAR
Initialization parameters: see SDK Initialization, RUM Configuration, Log Configuration, and Trace Configuration
Advanced capabilities: see the dedicated pages under “Advanced Scenarios”
Data model: see Application Data Collection
Troubleshooting: see Troubleshooting

Prerequisites¶

Note

If you have enabled RUM Headless, the prerequisites are already configured and you can integrate your app directly.

Install DataKit
Configure the RUM Collector
Configure DataKit to be publicly accessible over the internet and install the IP geolocation database

App Integration¶

Go to RUM > Create App > HarmonyOS
Enter the app name and app ID
Select the app integration method:
Public DataWay: receives RUM data directly, no DataKit collector installation required
Local environment deployment: receives RUM data after the prerequisites are met

Installation¶

Add the Hvigor Plugin Configuration¶

Automatic collection of console.* and hilog.*, as well as automatic cold start collection, depends on @cloudcare/hvigor-ohos-plugin. This plugin is a build-time toolkit and is not a runtime dependency of the app module's oh-package.json5.

Note: Cold start statistics use the rendering of the first UI frame as the end condition. @cloudcare/hvigor-ohos-plugin 0.1.1 requires ft_sdk 0.1.17 or later. HarmonyOS API 22 and above captures the actual first frame. On API levels below 22, a complete launch_cold Action and total cold start duration cannot be generated.

Add the dependency for the current (or a later) version of the plugin in the project-level hvigor/hvigor-config.json5:

{
  "dependencies": {
    "@cloudcare/hvigor-ohos-plugin": "^0.1.1"
  }
}

Then register the plugin in the app HAP module's hvigorfile.ts:

import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { ftConsoleLogPlugin } from '@cloudcare/hvigor-ohos-plugin';

export default {
  system: hapTasks,
  plugins: [ftConsoleLogPlugin()]
};

The plugin only transforms calls in the app's src/main/ets and does not rewrite source files or SDK dependencies on disk. The cold start code generated during compilation references ft_sdk, so the app must still keep ft_sdk as a runtime dependency. Perform a clean build after completing the configuration. If the plugin is not installed, console, hilog, or cold start data will not be collected automatically.

Add the SDK¶

Choose one of the following installation methods based on how your project is integrated.

Option 1: Install via ohpm¶

Once the third-party repository has been configured, you can install directly with ohpm:

ohpm install @guancecloud/ft_sdk

ohpm install @guancecloud/ft_sdk_ext #Optional
ohpm install @guancecloud/ft_native  #Optional

Option 2: Install via Local HAR¶

Following the HarmonyOS official documentation (HAR Package Import Guide), first prepare the packages as described in How to Obtain HAR, then place the HAR files in the project's libs directory and add scoped dependencies as needed in oh-package.json5.

{
  "dependencies": {
    "@guancecloud/ft_sdk": "file:../libs/ft_sdk.har",

    "@guancecloud/ft_sdk_ext": "file:../libs/ft_sdk_ext.har", //Optional
    "@guancecloud/ft_native": "file:../libs/ft_native.har"    //Optional
  }
}

If you use HAR package dependencies, it is recommended to also add overrides to the root oh-package.json5 of the project to rewrite the module's internal remote dependency to the local HAR, preventing ft_sdk_ext from continuing to resolve @guancecloud/ft_sdk from the remote repository:

//root/oh-package.json5
{
  "overrides": {
    "@guancecloud/ft_sdk": "file:./libs/ft_sdk.har"
  }
}

Then run:

ohpm install

After installation, the HAR packages are installed in the project's oh_modules/ directory. When using scoped dependencies, the directories typically appear as oh_modules/@guancecloud/ft_sdk, oh_modules/@guancecloud/ft_sdk_ext, and oh_modules/@guancecloud/ft_native.

Bytecode HAR Build Configuration¶

The ft_sdk 0.1.15, ft_sdk_ext 0.1.15, and ft_native 0.1.1 release packages use bytecode HAR. When integrating any of these packages, make sure:

The project must use HarmonyOS API 12 or higher. The HttpInterceptorChain capability of ft_sdk_ext requires HarmonyOS API 22 or higher.
In the root build-profile.json5 of the project, enable normalized OHMUrl for the actual build product. If a configuration with the same name already exists, just merge the strictMode content:

{
  "app": {
    "products": [
      {
        "name": "default",
        "buildOption": {
          "strictMode": {
            "useNormalizedOHMUrl": true
          }
        }
      }
    ]
  }
}

Dependency names in oh-package.json5 must match the SDK package names. Import APIs only from each package's public Index entry, and avoid internal paths such as src/main/....
Release packages have ArkGuard obfuscation enabled and preserve the public API through the consumer obfuscation rules shipped with the HAR. Do not delete or replace consumer-rules.txt inside the SDK package. When your app has obfuscation enabled, you can still use the SDK's public capabilities normally.

How to Obtain HAR¶

New Download Method¶

Go to the corresponding ohpm page first.
Then find the dist.tarball for the target version.
Download and extract the corresponding HAR package from the dist.tarball.

Corresponding URLs:

@guancecloud/ft_sdk: https://repo.harmonyos.com/ohpm/@guancecloud/ft_sdk
@guancecloud/ft_sdk_ext: https://repo.harmonyos.com/ohpm/@guancecloud/ft_sdk_ext
@guancecloud/ft_native: https://repo.harmonyos.com/ohpm/@guancecloud/ft_native

Note:

When downloading with the new method, select the dist.tarball that matches the version used in your project.
It is recommended to keep ft_sdk_ext and ft_sdk at the same version.
After downloading, you can still place the HAR files in the project's libs/ directory and continue integrating them via local HAR.

Legacy Download Method¶

Download the legacy ft_sdk.har file: Download Link
Download ft_sdk_ext.har as needed: Download Link
Download ft_native.har as needed: Download Link

Package Descriptions¶

Import the relevant packages as needed based on the capabilities you require:

ft_sdk.har is the core package and must be installed. When installed from a third-party repository, the corresponding package name is @guancecloud/ft_sdk.
ft_sdk_ext.har is the extension package. Install it when you need the HttpInterceptorChain automatic collection capability based on @kit.NetworkKit. This capability requires HarmonyOS API 22 or higher. When installed from a third-party repository, the corresponding package name is @guancecloud/ft_sdk_ext.
ft_native.har is an optional package. Install it only when you need native capabilities such as Native Crash. When installed from a third-party repository, the corresponding package name is @guancecloud/ft_native.
Only place the HAR files you actually use in the libs/ directory. If the directory does not exist, create it first. If the HAR files are currently in the project root directory, move them to the libs/ directory first.

Import Method¶

Import as follows:

import { FTSDK, FTSDKConfig, FTRUMConfig, FTLoggerConfig } from '@guancecloud/ft_sdk/Index';

To use the HTTP automatic collection capability based on HttpInterceptorChain, import it from @guancecloud/ft_sdk_ext:

import {
  applyFTHttpTrack,
  createFTHttpInterceptorChain
} from '@guancecloud/ft_sdk_ext/Index';

Notes:

@guancecloud/ft_sdk: Import entry for the default integration and Axios compatibility mode.
@guancecloud/ft_sdk_ext: Import entry for HttpInterceptorChain automatic collection (requires HarmonyOS API 22 or higher).
Axios compatibility paths such as applyFTAxiosTrack are still exported from @guancecloud/ft_sdk.

Permissions¶

The SDK already includes the following permission declarations, so no extra manual configuration is needed:

Permission Name	Description
`ohos.permission.INTERNET`	Network access permission for data reporting and network request tracing
`ohos.permission.GET_WIFI_INFO`	Obtains Wi-Fi information for network type detection and signal strength collection
`ohos.permission.GET_NETWORK_INFO`	Obtains network information for network status monitoring and type identification

Configuration Entry Points¶

Advanced Scenarios¶

Legacy Configuration Migration¶

This article describes how to migrate the HarmonyOS SDK from legacy package names and deep-path imports to the current scoped package names and the public Index entry. It applies to the following three types of projects:

Projects already integrated via local HAR that have used ft_sdk.har, ft_sdk_ext.har, or ft_native.har
Projects already installed via ohpm that still use legacy unscoped package name configuration or deep-path imports
Projects already migrated to @guancecloud/ scoped package names but whose code still imports from deep paths such as @guancecloud/ft_sdk/src/main/... or @guancecloud/ft_sdk_ext/src/main/...

Migration Overview¶

ft_sdk -> @guancecloud/ft_sdk
ft_sdk_ext -> @guancecloud/ft_sdk_ext
ft_native -> @guancecloud/ft_native
@guancecloud/ft_sdk/src/main/... -> @guancecloud/ft_sdk/Index
@guancecloud/ft_sdk_ext/src/main/... -> @guancecloud/ft_sdk_ext/Index

Note:

The HAR file names can continue to use ft_sdk.har, ft_sdk_ext.har, and ft_native.har.
What needs to be updated are the dependency names in oh-package.json5 and the import paths in code. We recommend using the SDK's public Index entry uniformly.
Whether installing via local HAR or ohpm, dependency names should be migrated uniformly to scoped package names, and code imports should be migrated uniformly to the public Index entry.
@guancecloud/.../src/main/... is the scoped deep-path style from previous versions. It can still be used as a migration reference, but it is not the latest recommended integration approach.
To obtain local HAR packages again, refer to How to Obtain HAR.

Configuration File Changes¶

Legacy syntax:

//root/entry/oh-package.json5
{
  "dependencies": {
    "ft_sdk": "file:../libs/ft_sdk.har",
    "ft_sdk_ext": "file:../libs/ft_sdk_ext.har",
    "ft_native": "file:../libs/ft_native.har"
  }
}

Previous scoped deep-path syntax:

//root/entry/oh-package.json5
{
  "dependencies": {
    "@guancecloud/ft_sdk": "file:../libs/ft_sdk.har",
    "@guancecloud/ft_sdk_ext": "file:../libs/ft_sdk_ext.har",
    "@guancecloud/ft_native": "file:../libs/ft_native.har"
  }
}

//root/oh-package.json5
{
  "overrides": {
    "@guancecloud/ft_sdk": "file:./libs/ft_sdk.har"
  }
}

If installing via ohpm, the dependency names also need to be changed to scoped package names, for example:

ohpm install @guancecloud/ft_sdk
ohpm install @guancecloud/ft_sdk_ext
ohpm install @guancecloud/ft_native

Comparison notes:

The new syntax changes the dependency names from the legacy ft_sdk, ft_sdk_ext, and ft_native to scoped package names.
If installing via ohpm, use the new scoped package names in the installation commands as well.
overrides must be configured in the root oh-package.json5 of the project.
When the project integrates ft_sdk_ext.har via local HAR, overrides["@guancecloud/ft_sdk"] is used to rewrite its internal remote dependency to the local ft_sdk.har.
If you only use ft_sdk.har or ft_native.har, keep the corresponding dependencies as needed.

Code Import Changes¶