Skip to content

HarmonyOS Application Integration

Collect metrics data from HarmonyOS applications and analyze application performance visually.

Reading Path

Prerequisites

Note

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

Application Integration

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

Installation

Choose any of the following installation methods based on the project integration method.

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 HarmonyOS official documentation (HAR Package Import Guide), first refer to HAR Acquisition Methods to prepare the installation package, 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 directory'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 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.

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:

Please note:

  • When downloading using the new method, select the dist.tarball consistent with the project integration version
  • ft_sdk_ext and ft_sdk are recommended to maintain the same version
  • The downloaded HAR file can still be placed in the project's libs/ directory and integrated via the local HAR method

Old HAR Download Method

Package Description

Please introduce related packages as needed based on actual capabilities:

  • 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
  • ft_sdk_ext.har is an extension package, installed only when automatic collection capability based on @kit.NetworkKit's HttpInterceptorChain is needed. HttpInterceptor related capabilities are supported from 0.1.14-alpha03 onwards and depend on HarmonyOS API 22 or higher; when installed via a third-party repository, the corresponding package name is @guancecloud/ft_sdk_ext
  • ft_native.har is an optional package, installed only when native capabilities such as Native Crash are needed; when installed via a third-party repository, the corresponding package name 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 file is currently in the project root directory, move it to the libs/ directory first

Import Methods

You can import in the following ways:

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

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

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

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 such as applyFTAxiosTrack are still exported from @guancecloud/ft_sdk

Permission Description

The SDK already automatically includes the following permission declarations, no need for manual additional configuration:

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

Detailed Configuration Entries

Advanced Scenarios

Old Configuration Migration

This article explains how to migrate HarmonyOS SDK from old package names and deep path imports to the current scoped package names and public Index entry. It applies to the following three 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 using old unscoped package name configurations or deep path imports
  • Already migrated to @guancecloud/ scoped package names, but the code still imports from @guancecloud/ft_sdk/src/main/... or @guancecloud/ft_sdk_ext/src/main/... deep paths

Migration Content 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

Please note:

  • The HAR file names 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; it is recommended to uniformly use the SDK's public Index entry
  • Whether installed via local HAR or via ohpm, dependency names should be uniformly migrated to scoped package names, and code imports should be uniformly migrated to the public Index entry
  • @guancecloud/.../src/main/... belongs to the scoped deep path writing method of previous versions and can continue to be used as a migration reference, but is not the latest recommended integration method
  • If you need to reacquire local HAR packages, refer to HAR Acquisition Methods

Configuration File Changes

Old writing:

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

//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 name also needs 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 explanation:

  • The new writing changes the dependency names from the old ft_sdk, ft_sdk_ext, ft_native to scoped package names
  • If installed via ohpm, the new scoped package name should also be used for the installation command
  • overrides needs to be configured in the project root directory'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

Old writing:

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

Previous scoped deep path writing:

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 writing:

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

Migration Steps

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

Common 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, for example, df_tag_name. When there are fields with the same name in SDK global variables and RUM, Log, the fields in RUM, Log will override the SDK global variables.

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

Feedback

Is this page helpful? ×