HarmonyOS Application Access¶

By collecting metrics data from HarmonyOS applications, you can analyze application performance visually.

Reading Paths¶

1. For first-time access: Read Quick Start first.
2. For complete access: Continue reading this document.
3. For old package name migration: See Old Configuration Migration.
4. For HAR package download: See HAR Access Methods.
5. For initialization parameters: See SDK Initialization, RUM Configuration, Log Configuration, and Trace Configuration.
6. For custom tags: See Custom Tags and Global Context.
7. For advanced scenarios: See WebView Data Monitoring.
8. For data models: See Application Data Collection.
9. For troubleshooting: See Fault Diagnosis.

Prerequisites¶

1. Install DataKit.
2. Configure the RUM Collector.
3. Configure DataKit to be publicly accessible and install the IP geolocation database.

Application Access¶

1. Go to RUM > Create Application > HarmonyOS.
2. Enter the application name and application ID.
3. Select the application access method:
4. Public DataWay: Directly receives RUM data without installing the DataKit collector.
5. Local Environment Deployment: Receives RUM data after meeting the prerequisites.

Installation¶

Depending on the project access method, choose one of the following installation schemes.

Scheme 1: Install via ohpm¶

When the third-party repository has been configured, you can install directly using ohpm:

ohpm install @guancecloud/ft_sdk

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

Scheme 2: Install via Local HAR¶

According to the HarmonyOS official documentation (HAR Package Import Guide), please first refer to HAR Access Methods to prepare the installation package, then place the HAR files in the project's libs directory and add scoped dependencies in oh-package.json5 as needed.

{
  "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 add overrides in the root directory's oh-package.json5 to rewrite the internal remote dependencies to local HAR files, 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 package will be installed in the project's oh_modules/ directory. When using scoped dependencies, the directory typically appears as oh_modules/@guancecloud/ft_sdk, oh_modules/@guancecloud/ft_sdk_ext, 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 accessing any such package, please confirm:

1. The project's HarmonyOS API Level is 12 or higher; the HttpInterceptorChain capability of ft_sdk_ext still requires API Level 22 or higher.
2. In the project root directory's build-profile.json5, enable normalized OHMUrl for the actual build product. If a configuration with the same name already exists, only merge the strictMode content:

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

1. The dependency name in oh-package.json5 should be consistent with the SDK package name; code should only import APIs from the public Index entry of each package, avoiding internal paths like src/main/....
2. The Release package has enabled ArkGuard obfuscation and retains public APIs through the consumer obfuscation rules released with the HAR. Do not delete or replace the consumer-rules.txt file inside the SDK package; when the application itself enables obfuscation, the SDK public capabilities can still be called normally.

HAR Access Methods¶

New HAR Access Methods¶

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

Corresponding addresses:

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

Please note:

1. When downloading with the new method, choose a dist.tarball that is consistent with the project access version.
2. It is recommended to keep ft_sdk_ext and ft_sdk at the same version.
3. The downloaded HAR files can still be placed in the project's libs/ directory and accessed as local HAR files.

Old HAR Download Methods¶

1. Download the old version of the ft_sdk.har file: Download Link
2. Download the ft_sdk_ext.har file as needed: Download Link
3. Download the ft_native.har file as needed: Download Link

Package Descriptions¶

Please introduce the relevant packages based on actual capabilities:

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

You can import in the following way:

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

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

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

Notes:

1. @guancecloud/ft_sdk: The default import entry for access and Axios compatibility mode.
2. @guancecloud/ft_sdk_ext: The import entry for HttpInterceptorChain automatic collection related.
3. Axios compatibility paths such as applyFTAxiosTrack are still exported from @guancecloud/ft_sdk.

Permissions Description¶

The SDK has automatically included the following permission declarations, no manual additional configuration is needed:

Detailed Configuration Entry Points¶

1. SDK Initialization
2. RUM Configuration
3. Log Configuration
4. Trace Configuration

Advanced Scenarios¶

1. Custom Tags and Global Context
2. WebView Data Monitoring

Old Configuration Migration¶

This document explains how to migrate the HarmonyOS SDK from the old package name and deep path import to the current scoped package name and public Index entry. It is applicable to the following three types of projects:

1. Projects that have already been accessed via local HAR method and have used ft_sdk.har, ft_sdk_ext.har, ft_native.har.
2. Projects that have been installed via ohpm but still use the old unscoped package name configuration or deep path imports.
3. Projects that have migrated to the @guancecloud/ scoped package name but still import from deep paths like @guancecloud/ft_sdk/src/main/... or @guancecloud/ft_sdk_ext/src/main/....

Migration Content Overview¶

1. ft_sdk -> @guancecloud/ft_sdk
2. ft_sdk_ext -> @guancecloud/ft_sdk_ext
3. ft_native -> @guancecloud/ft_native
4. @guancecloud/ft_sdk/src/main/... -> @guancecloud/ft_sdk/Index
5. @guancecloud/ft_sdk_ext/src/main/... -> @guancecloud/ft_sdk_ext/Index

Please note:

1. The HAR file names can continue to be ft_sdk.har, ft_sdk_ext.har, ft_native.har.
2. What needs to be adjusted are the dependency names in oh-package.json5 and the import paths in the code; it is recommended to uniformly use the SDK public Index entry.
3. Whether installed via local HAR or via ohpm, the dependency names should be uniformly migrated to the scoped package name, and code imports should be uniformly migrated to the public Index entry.
4. @guancecloud/.../src/main/... is a scoped deep path format from previous versions, which can continue to be used as a migration reference but is not recommended as the latest access method.
5. If you need to obtain the local HAR package again, please refer to HAR Access Methods.

Configuration File Changes¶

Old format:

//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 format:

//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 installed via ohpm, the dependency names also need to be changed to the scoped package name, for example:

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

Comparison notes:

1. The new format changes the dependency names from the old ft_sdk, ft_sdk_ext, ft_native to the scoped package name.
2. If installed via ohpm, the installation command should also use the new scoped package name.
3. overrides needs to be configured in the root directory's oh-package.json5.
4. When the project accesses 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.
5. If only ft_sdk.har or ft_native.har is used, the corresponding dependencies can be retained as needed.

Code Import Changes¶

Old format:

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 format (first step - scoped deep path):

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';

New format (recommended - public Index entry):

import { FTSDK, FTSDKConfig } from '@guancecloud/ft_sdk/Index';
import { createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/Index';

Migration Steps¶

1. Place the HAR files in the project's libs/ directory.
2. Change the dependency names in the project from the old package name to the new scoped package name.
3. If the project uses ft_sdk_ext.har via local HAR, add overrides in the root directory's oh-package.json5.
4. If the project was installed via ohpm, re-execute the installation command with the new scoped package name; if installed via local HAR, execute ohpm install.
5. Replace the old import paths or the previous @guancecloud/.../src/main/... scoped deep paths in the code with the public Index entry.

Frequently Asked Questions¶

How to Avoid Conflicting 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 a global variable in the SDK has the same field name as a field in RUM or Log, the field in RUM or Log will override the one in the SDK global variable.

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