HarmonyOS Application Integration¶

Collect Metrics data from HarmonyOS applications and analyze application performance through visualization.

Reading Path¶

First-time integration: Start with Quick Start
Complete integration: Continue reading this article
Legacy package name migration: Refer to Legacy Configuration Migration
HAR package download: Refer to HAR Acquisition Methods
Initialization parameters: Refer to SDK Initialization, RUM Configuration, Log Configuration, Trace Configuration
Custom tags: Refer to Custom Tags and Global Context
Advanced scenarios: Refer to WebView Data Monitoring
Data model: Refer to Application Data Collection
Troubleshooting: Refer to Troubleshooting

Prerequisites¶

Note

If you have already activated the RUM Headless service, the prerequisites are automatically configured, and you can directly integrate the application.

Install DataKit
Configure the RUM collector
Configure DataKit to be accessible via the public network and install the IP geolocation database

Application Integration¶

Navigate to RUM > Create > HarmonyOS
Enter the application name and application ID
Select the application integration method:
Public DataWay: Directly receives RUM data without installing the DataKit collector
Local environment deployment: Receives RUM data after meeting the prerequisites

Installation¶

Choose any of the following installation methods based on your project's integration approach.

Method 1: Install via ohpm¶

If the third-party repository is already configured, you can install directly via ohpm:

ohpm install @guancecloud/ft_sdk

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

Method 2: Install via Local HAR¶

According to the official HarmonyOS documentation (HAR Package Import Guide), first prepare the installation package by referring to HAR Acquisition Methods. Then place the HAR file 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 using HAR package dependencies, it is recommended to also add overrides in the project root's oh-package.json5 to rewrite the internal remote dependencies of the module 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 execute:

ohpm install

After installation, the HAR packages will be 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, oh_modules/@guancecloud/ft_native.

HAR Acquisition Methods¶

New HAR Acquisition Method¶

First, go to the corresponding ohpm page
Then find the dist.tarball for the target version
Download from dist.tarball and extract the corresponding HAR package

Corresponding addresses:

@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

Please note:

When downloading using the new method, select the dist.tarball consistent with the project's integration version
It is recommended to keep ft_sdk_ext and ft_sdk at the same version
The downloaded HAR files can still be placed in the project's libs/ directory and integrated using the local HAR method

Legacy HAR Download Method¶

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

Package Description¶

Introduce relevant packages as needed based on actual capabilities:

ft_sdk.har is the core package and must be installed; the corresponding package name when installing via a third-party repository is @guancecloud/ft_sdk
ft_sdk_ext.har is an extension package, installed only when automatic collection capabilities based on @kit.NetworkKit's HttpInterceptorChain are needed. HttpInterceptor related capabilities are supported from version 0.1.14-alpha03 onwards and depend on HarmonyOS API 22 or higher; the corresponding package name when installing via a third-party repository is @guancecloud/ft_sdk_ext
ft_native.har is an optional package, installed only when native capabilities like Native Crash are needed; the corresponding package name when installing via a third-party repository is @guancecloud/ft_native
Only place the HAR files actually used into 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 Methods¶

You can import as follows:

import { FTSDK } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig, FTRUMConfig, FTLoggerConfig } from '@guancecloud/ft_sdk/src/main/ets/components/Configs';

If you need to use HTTP automatic collection capabilities based on HttpInterceptorChain, import from @guancecloud/ft_sdk_ext:

import { applyFTHttpTrack, createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/src/main/ets/components/network/FTHttpAutoTrackExt';

Explanation:

@guancecloud/ft_sdk: Default integration and Axios-compatible mode import entry
@guancecloud/ft_sdk_ext: HttpInterceptorChain automatic collection related import entry
Axios-compatible paths like applyFTAxiosTrack are still exported from @guancecloud/ft_sdk

Permission Description¶

The SDK automatically includes the following permission declarations, no manual additional configuration is required:

Permission Name	Purpose Description
`ohos.permission.INTERNET`	Network access permission, used for data reporting and network request tracking
`ohos.permission.GET_WIFI_INFO`	Obtain WiFi information, used for network type detection and signal strength collection
`ohos.permission.GET_NETWORK_INFO`	Obtain network information, used for network status monitoring and type identification

Detailed Configuration Entries¶

Advanced Scenarios¶

Legacy Configuration Migration¶

This article explains how to migrate the HarmonyOS SDK from legacy package names to the current scoped package names. It applies to the following two types of projects:

Already integrated via local HAR method and have used ft_sdk.har, ft_sdk_ext.har, ft_native.har
Already installed via ohpm, but still use legacy unscoped package name configurations or import paths

Migration Overview¶

ft_sdk -> @guancecloud/ft_sdk
ft_sdk_ext -> @guancecloud/ft_sdk_ext
ft_native -> @guancecloud/ft_native

Please note:

The HAR filenames themselves can continue to be used as ft_sdk.har, ft_sdk_ext.har, ft_native.har
What needs adjustment are the dependency names in oh-package.json5 and the import paths in the code
Whether installing via local HAR or via ohpm, the dependency names and import paths should be uniformly migrated to scoped package names
If you need to reacquire local HAR packages, refer to HAR Acquisition Methods

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"
  }
}

New 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 explanation:

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

Code Import Changes¶

Legacy syntax:

import { FTSDK } from 'ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig } from 'ft_sdk/src/main/ets/components/Configs';
import { createFTHttpInterceptorChain } from 'ft_sdk_ext/src/main/ets/components/network/FTHttpAutoTrackExt';

New syntax:

import { FTSDK } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig } from '@guancecloud/ft_sdk/src/main/ets/components/Configs';
import { createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/src/main/ets/components/network/FTHttpAutoTrackExt';

Migration Steps¶

Place the HAR files in the project's libs/ directory
Change the dependency names in the project from the legacy package names to the new scoped package names
If the project uses ft_sdk_ext.har via the local HAR method, add overrides in the project root's oh-package.json5
If the project installs via ohpm, re-execute the installation command using the new scoped package names; if the project installs via local HAR, execute ohpm install
Replace the legacy import paths in the code with the new scoped paths

Frequently Asked Questions¶

How to Avoid Conflict Fields When Adding Global Variables¶

To avoid conflicts between custom fields and SDK data, it is recommended to add a business prefix to tag names, such as df_tag_name. When an SDK global variable has the same name as a field in RUM or Log, the field in RUM or Log will override the SDK global variable.

For usage of custom tags, continue reading Custom Tags and Global Context.