HarmonyOS 애플리케이션 연동¶

HarmonyOS 애플리케이션의 메트릭 데이터를 수집하여 애플리케이션 성능을 시각화 방식으로 분석합니다.

읽기 경로¶

최초 연동: 빠른 시작 참조
전체 연동: 본 문서 계속 읽기
구 버전 패키지 이름 마이그레이션: 구 설정 마이그레이션 참조
HAR 패키지 다운로드: HAR 다운로드 방법 참조
초기화 매개변수: SDK 초기화, RUM 설정, Log 설정, Trace 설정 참조
사용자 정의 태그: 사용자 정의 태그 및 전역 컨텍스트 참조
고급 시나리오: WebView 데이터 모니터링 참조
데이터 모델: 애플리케이션 데이터 수집 참조
문제 해결: 문제 해결 참조

전제 조건¶

참고

RUM Headless 서비스를 이미 활성화한 경우, 전제 조건이 자동으로 구성되어 애플리케이션을 바로 연동할 수 있습니다.

DataKit 설치
RUM 수집기 설정
DataKit을 공개 네트워크에서 액세스 가능하게 설정하고 IP 지리 정보 데이터베이스 설치

애플리케이션 연동¶

실제 사용자 모니터링(RUM) > 애플리케이션 생성 > HarmonyOS 로 이동
애플리케이션 이름과 애플리케이션 ID 입력
애플리케이션 연동 방식 선택:
공용 DataWay: DataKit 수집기 설치 없이 RUM 데이터를 직접 수신
로컬 환경 배포: 전제 조건 충족 후 RUM 데이터 수신

설치¶

프로젝트 연동 방식에 따라 다음 설치 방법 중 하나를 선택하세요.

방법 1: ohpm으로 설치¶

타사 저장소가 이미 구성된 경우, ohpm을 통해 직접 설치할 수 있습니다.

ohpm install @guancecloud/ft_sdk

ohpm install @guancecloud/ft_sdk_ext #선택 사항
ohpm install @guancecloud/ft_native  #선택 사항

방법 2: 로컬 HAR로 설치¶

HarmonyOS 공식 문서(HAR 패키지 가져오기 가이드)에 따라 HAR 다운로드 방법을 참조하여 설치 패키지를 준비한 후, HAR 파일을 프로젝트의 libs 디렉터리에 넣고 oh-package.json5에 필요한 scoped 의존성을 추가하세요.

{
  "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"    //선택 사항
  }
}

HAR 패키지 의존성을 사용하는 경우, 프로젝트 루트의 oh-package.json5에 overrides를 함께 추가하여 모듈 내부의 원격 의존성을 로컬 HAR로 재정의하는 것이 좋습니다. 이렇게 하면 ft_sdk_ext가 계속해서 원격 저장소에서 @guancecloud/ft_sdk를 확인하는 것을 방지할 수 있습니다.

//root/oh-package.json5
{
  "overrides": {
    "@guancecloud/ft_sdk": "file:./libs/ft_sdk.har"
  }
}

그런 다음 실행:

ohpm install

설치가 완료되면 HAR 패키지가 프로젝트의 oh_modules/ 디렉터리에 설치됩니다. scoped 의존성을 사용하는 경우 디렉터리는 일반적으로 oh_modules/@guancecloud/ft_sdk, oh_modules/@guancecloud/ft_sdk_ext, oh_modules/@guancecloud/ft_native 형태로 나타납니다.

바이트코드 HAR 빌드 설정¶

ft_sdk 0.1.15, ft_sdk_ext 0.1.15, ft_native 0.1.1 릴리스 패키지는 바이트코드 HAR을 사용합니다. 이러한 패키지를 연동할 때는 다음을 확인하세요.

프로젝트의 HarmonyOS API Level이 12 이상이어야 합니다. ft_sdk_ext의 HttpInterceptorChain 기능은 여전히 API Level 22 이상이 필요합니다.
프로젝트 루트의 build-profile.json5에서 실제 빌드 제품에 대해 정규화된 OHMUrl을 활성화합니다. 동일한 이름의 설정이 이미 있는 경우 strictMode 내용만 병합하면 됩니다.

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

oh-package.json5의 의존성 이름은 SDK 패키지 이름과 일치해야 합니다. 코드는 각 패키지의 공개 Index 진입점에서만 API를 가져오고, src/main/... 등 내부 경로는 사용하지 마세요.
릴리스 패키지에는 ArkGuard 난독화가 활성화되어 있으며, HAR과 함께 제공되는 소비자 난독화 규칙을 통해 공개 API가 유지됩니다. SDK 패키지 내의 consumer-rules.txt를 삭제하거나 교체하지 마세요. 애플리케이션 자체에서 난독화를 활성화한 경우에도 SDK 공개 기능을 정상적으로 호출할 수 있습니다.

HAR 다운로드 방법¶

새 HAR 다운로드 방법¶

먼저 해당 ohpm 페이지로 이동
대상 버전의 dist.tarball 찾기
dist.tarball에서 해당 HAR 패키지 다운로드 및 압축 해제

해당 주소:

@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

참고:

새 방식으로 다운로드할 때는 프로젝트 연동 버전과 일치하는 dist.tarball을 선택하세요.
ft_sdk_ext와 ft_sdk는 동일한 버전을 유지하는 것이 좋습니다.
다운로드한 HAR 파일은 계속해서 프로젝트의 libs/ 디렉터리에 넣어 로컬 HAR 방식으로 연동할 수 있습니다.

구 HAR 다운로드 방법¶

구 버전 ft_sdk.har 파일 다운로드: 다운로드 주소
필요 시 ft_sdk_ext.har 파일 다운로드: 다운로드 주소
필요 시 ft_native.har 파일 다운로드: 다운로드 주소

패키지 설명¶

실제 필요에 따라 관련 패키지를 선택적으로 가져오세요.

ft_sdk.har는 핵심 패키지로 반드시 설치해야 합니다. 타사 저장소를 통해 설치할 때는 @guancecloud/ft_sdk 패키지 이름에 해당합니다.
ft_sdk_ext.har는 확장 패키지로, @kit.NetworkKit 기반의 HttpInterceptorChain을 사용한 자동 수집 기능이 필요한 경우에만 설치합니다. HttpInterceptor 관련 기능은 0.1.14-alpha03부터 지원되며, HarmonyOS API 22 이상이 필요합니다. 타사 저장소를 통해 설치할 때는 @guancecloud/ft_sdk_ext 패키지 이름에 해당합니다.
ft_native.har는 선택적 패키지로, Native Crash 등 네이티브 기능이 필요한 경우에만 설치합니다. 타사 저장소를 통해 설치할 때는 @guancecloud/ft_native 패키지 이름에 해당합니다.
실제로 사용하는 HAR 파일만 libs/ 디렉터리에 넣으면 됩니다. 디렉터리가 없는 경우 먼저 생성하고, HAR 파일이 현재 프로젝트 루트 디렉터리에 있는 경우 먼저 libs/ 디렉터리로 이동하세요.

가져오기 방법¶

다음과 같이 가져올 수 있습니다.

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

HttpInterceptorChain 기반 HTTP 자동 수집 기능을 사용하려면 @guancecloud/ft_sdk_ext에서 가져오세요.

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

설명:

@guancecloud/ft_sdk: 기본 연동 및 Axios 호환 모드의 가져오기 진입점
@guancecloud/ft_sdk_ext: HttpInterceptorChain 자동 수집 관련 가져오기 진입점
applyFTAxiosTrack 등 Axios 호환 경로는 여전히 @guancecloud/ft_sdk에서 내보냅니다.

권한 설명¶

SDK에 이미 다음 권한 선언이 포함되어 있으므로 별도로 추가할 필요가 없습니다.

권한 이름	용도 설명
`ohos.permission.INTERNET`	네트워크 액세스 권한, 데이터 업로드 및 네트워크 요청 추적에 사용
`ohos.permission.GET_WIFI_INFO`	WiFi 정보 획득, 네트워크 유형 감지 및 신호 강도 수집에 사용
`ohos.permission.GET_NETWORK_INFO`	네트워크 정보 획득, 네트워크 상태 모니터링 및 유형 식별에 사용

세부 설정 진입점¶

고급 시나리오¶

구 설정 마이그레이션¶

이 문서는 HarmonyOS SDK가 구 버전 패키지 이름 및 깊은 경로 가져오기에서 현재의 scoped 패키지 이름 및 공개 Index 진입점으로 마이그레이션하는 방법을 설명합니다. 다음 세 가지 유형의 프로젝트에 적용됩니다.

이미 로컬 HAR 방식으로 연동하고 ft_sdk.har, ft_sdk_ext.har, ft_native.har를 사용한 적이 있는 경우
이미 ohpm으로 설치했지만, 여전히 구 버전의 scope가 없는 패키지 이름 설정이나 깊은 경로 가져오기를 사용하는 경우
이미 @guancecloud/ scoped 패키지 이름으로 마이그레이션했지만, 코드가 여전히 @guancecloud/ft_sdk/src/main/... 또는 @guancecloud/ft_sdk_ext/src/main/... 깊은 경로에서 가져오는 경우

마이그레이션 내용 개요¶

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

참고:

HAR 파일 이름은 ft_sdk.har, ft_sdk_ext.har, ft_native.har를 계속 사용할 수 있습니다.
수정해야 할 것은 oh-package.json5의 의존성 이름과 코드의 가져오기 경로입니다. SDK 공개 Index 진입점을 통일하여 사용하는 것을 권장합니다.
로컬 HAR 설치든 ohpm 설치든, 의존성 이름은 scoped 패키지 이름으로 통일하고, 코드 가져오기는 공개 Index 진입점으로 통일해야 합니다.
@guancecloud/.../src/main/...는 이전 버전의 scoped 깊은 경로 표기법으로, 마이그레이션 참고용으로 계속 사용할 수 있지만 최신 권장 연동 방식은 아닙니다.
로컬 HAR 패키지를 다시 받아야 하는 경우 HAR 다운로드 방법을 참조하세요.

설정 파일 변경¶

구 표기법:

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

이전 scoped 깊은 경로 표기법:

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

ohpm으로 설치하는 경우에도 의존성 이름을 scoped 패키지 이름으로 변경해야 합니다. 예:

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

비교 설명:

새 표기법은 의존성 이름을 구 ft_sdk, ft_sdk_ext, ft_native에서 scoped 패키지 이름으로 변경합니다.
ohpm으로 설치하는 경우에도 새 scoped 패키지 이름으로 설치 명령을 실행해야 합니다.
overrides는 프로젝트 루트의 oh-package.json5에 설정해야 합니다.
프로젝트가 로컬 HAR 방식으로 ft_sdk_ext.har를 연동하는 경우, overrides["@guancecloud/ft_sdk"]를 사용하여 내부의 원격 의존성을 로컬 ft_sdk.har로 재정의합니다.
ft_sdk.har 또는 ft_native.har만 사용하는 경우 실제 필요에 따라 해당 dependencies를 유지하면 됩니다.

코드 가져오기 변경¶