Skip to content

Quick Start

This document provides the shortest integration path for the HarmonyOS RUM SDK, helping you quickly complete a verifiable data report.

Prerequisites

  1. Create a HarmonyOS app in RUM and obtain the RUM App ID
  2. Determine the reporting method:
    • On-premises deployment: prepare datakitUrl
    • Public DataWay: prepare datawayUrl and clientToken
  3. Choose an installation method:
    • If a third-party repository is configured: install @guancecloud/ft_sdk directly via ohpm
    • Use a local HAR: download ft_sdk.har and use @guancecloud/ft_sdk as the dependency name in oh-package.json5
  4. To use the HTTP interceptor chain capability based on @kit.NetworkKit, additionally install @guancecloud/ft_sdk_ext or download ft_sdk_ext.har. This capability requires HarmonyOS API 22 or later.
  5. To collect Native Crash, additionally install @guancecloud/ft_native or download ft_native.har
  6. When using the bytecode HAR, the project must use HarmonyOS API 12 or later and enable useNormalizedOHMUrl in the root build-profile.json5. For complete configuration and obfuscation instructions, see Bytecode HAR Build Configuration.

Integration Steps

  1. When using a third-party repository, run ohpm install @guancecloud/ft_sdk
  2. When using a local HAR, place the HAR file in the project libs directory and declare the scoped dependency in oh-package.json5. If ft_sdk_ext.har is also used, use overrides in the root oh-package.json5 to rewrite @guancecloud/ft_sdk to the local HAR before running ohpm install
  3. Initialize FTSDKConfig at app startup
  4. Initialize FTRUMConfig to enable View, Action, Resource, ANR, and Crash collection
  5. Enable debug logging, run the app, and trigger a page open or network request
  6. Return to the console to confirm that the RUM data was reported successfully

Minimal Dependency Setup

  • Install the core SDK via ohpm:
ohpm install @guancecloud/ft_sdk
  • When using a local HAR, add the minimal dependency in oh-package.json5:
{
  "dependencies": {
    "@guancecloud/ft_sdk": "file:../libs/ft_sdk.har"
  }
}

It is recommended to integrate with the minimal dependencies first. After basic data reporting works, add extension packages as needed.

Minimal Initialization Example

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

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


export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // For on-premises deployment, use FTSDKConfig.builder(datakitUrl) instead
    const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
      .setDebug(true)
      .setSdkLogLevel(SDKLogLevel.D)
      .setServiceName('Your-App-Name')
      .setEnv(EnvType.PROD);

    FTSDK.install(sdkConfig, this.context);

    const rumConfig = new FTRUMConfig()
      .setRumAppId('your-app-id')
      .setSamplingRate(1.0)
      .setEnableTraceUserAction(true)
      .setEnableTraceUserView(true)
      .setEnableTraceUserResource(true)
      .setEnableTrackAppANR(true)
      .setEnableTrackAppCrash(true);

    FTSDK.installRUMConfig(rumConfig);
  }
}

Verify the Integration

  1. Keep setDebug(true) enabled
  2. Open a page or initiate a network request
  3. Search for [FT-SDK] in hilog to confirm that the SDK initialization and data reporting flow are normal
  4. Return to the Guance console to confirm that the corresponding RUM data appears

Next Steps

Feedback

Is this page helpful?