HarmonyOS SDK integration

Introduction

This SDK is based on HarmonyOS API 12. The compatibleSdkVersion is 5.0.0(12).

Preparations

1. Set up your HarmonyOS application development environment. For more information, see the HarmonyOS Application Development Guide.

2. Create a HarmonyOS application and obtain the AppKey and AppSecret from the application settings. For more information, see Connect to the SDK.

Step 1: Install the SDK

Run the following commands in the root directory of your HarmonyOS application to install the SDK:

ohpm install @aliyun/apm
ohpm install @aliyun/apm_crash

For more information about the ohpm tool and installing third-party SDKs on OpenHarmony, see the OpenHarmony Third-party Library Central Repository Guide.

Step 2: Initialize the SDK and start Crash Analytics

Add the following code to the Ability onCreate lifecycle callback to initialize and configure the SDK:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { APM, APMConfig, Logger } from '@aliyun/apm';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { crashAnalysisApi } from '@aliyun/apm_crash';

class MyCustomLog implements Logger {
  print(domain: number, tag: string, level: hilog.LogLevel, msg: string): void {
    switch (level) {
      case hilog.LogLevel.DEBUG:
        console.debug(`Custom log msg:${msg}`);
        break;
      case hilog.LogLevel.INFO:
        console.info(`Custom log msg:${msg}`);
        break;
      case hilog.LogLevel.WARN:
        console.warn(`Custom log msg:${msg}`);
        break;
      case hilog.LogLevel.ERROR:
      case hilog.LogLevel.FATAL:
        console.error(`Custom log msg:${msg}`);
        break;
    }
  }
}

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');

    const apm_perf_config: APMConfig = {
      context: this.context,
      appKey: 'Your AppKey',
      appSecret: 'Your AppSecret',
      nick: 'User nickname parameter',
      userId: 'User ID parameter',
      channel: 'User channel parameter',
      hiLog: true, // Switch for hilog in the SDK
      customLogger: new MyCustomLog(), // Custom log interface
    }
    APM.init(apm_perf_config, [crashAnalysisApi])
    APM.start();

  }

  // Omit other code
}

Set `appKey` and `appSecret` to the AppKey and AppSecret that you obtained in the Preparations section.

Step 3: Verify the integration

After you integrate the SDK, verify that it is working correctly:

1. Write test code to simulate or trigger an application crash. For example:

   arkts

    // Array-index out of bounds
     let tempList = ['a', 'b']
     hilog.info(0x0000, 'apm', 'jsCrash %s', tempList[3].toString())

2. Restart the application. After about 2 minutes, check the console to see if the crash information is displayed.

   Note

   There is a delay of about 2 to 3 minutes from when crash data is collected until it is uploaded and displayed on the console.

Upgrading from version 1.0.0 to 1.0.1

Version 1.0.1 optimizes the initialization interface compared to version 1.0.0. This change supports more application performance management (APM) products, such as App Performance Analytics.

Adjust the code from Step 2 and update your integration code. For more information, see Step 2: Initialize the SDK and start Crash Analytics.

To integrate both App Performance Analytics and Crash Analytics, you must call two APIs during initialization, as shown in the following core code:

// Omit import code

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');

    const apm_perf_config: APMConfig = {
      context: this.context,
      appKey: 'Your AppKey',
      appSecret: 'Your AppSecret',
      nick: 'User nickname parameter',
      userId: 'User ID parameter',
      channel: 'User channel parameter',
      hiLog: true, // Switch for hilog in the SDK
      customLogger: new MyCustomLog(), // Custom log interface
    }
    // Call two APIs during init
    APM.init(apm_perf_config, [crashAnalysisApi, performanceApi])
    APM.start();

  }

  // Omit other code
}