HarmonyOS 앱 연동¶

HarmonyOS 앱의 메트릭 데이터를 수집하여 앱 성능을 시각적으로 분석합니다.

읽기 경로¶

최초 연동: 빠른 시작을 먼저 확인하세요
전체 연동: 이 문서를 계속 읽어 보세요
구버전 패키지명 마이그레이션: 이전 설정 마이그레이션 참조
HAR 패키지 다운로드: HAR 받는 방법 참조
초기화 매개변수: SDK 초기화, RUM 설정, Log 설정, Trace 설정 참조
고급 기능: “고급 시나리오” 그룹의 전용 문서 참조
데이터 모델: 앱 데이터 수집 참조
문제 해결: 트러블슈팅 참조

전제 조건¶

주의

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

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

앱 연동¶

RUM > 앱 생성 > HarmonyOS로 이동합니다.
앱 이름과 앱 ID를 입력합니다.
앱 연동 방식을 선택합니다:
퍼블릭 DataWay: DataKit 수집기 설치 없이 RUM 데이터를 직접 수신합니다
로컬 환경 배포: 전제 조건을 충족한 후 RUM 데이터를 수신합니다

설치¶

Hvigor Plugin 구성 추가¶

console.*, hilog.* 자동 수집과 콜드 스타트 자동 수집은 @cloudcare/hvigor-ohos-plugin에 의존합니다. 이 플러그인은 빌드 타임 도구 패키지로, 앱 모듈의 oh-package.json5 런타임 종속성에 포함되지 않습니다.

참고: 콜드 스타트 통계는 첫 번째 UI 프레임이 렌더링될 때 종료됩니다. @cloudcare/hvigor-ohos-plugin 0.1.1은 ft_sdk 0.1.17 이상이 필요합니다. HarmonyOS API 22 이상에서는 실제 첫 프레임을 수집합니다. API 22 미만에서는 완전한 launch_cold Action과 콜드 스타트 총 소요 시간을 생성할 수 없습니다.

프로젝트 수준의 hvigor/hvigor-config.json5에 현재 버전(또는 이후 버전)의 플러그인 종속성을 추가합니다:

{
  "dependencies": {
    "@cloudcare/hvigor-ohos-plugin": "^0.1.1"
  }
}

그런 다음 앱 HAP 모듈의 hvigorfile.ts에 플러그인을 등록합니다:

import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { ftConsoleLogPlugin } from '@cloudcare/hvigor-ohos-plugin';

export default {
  system: hapTasks,
  plugins: [ftConsoleLogPlugin()]
};

플러그인은 앱 src/main/ets의 호출만 변환하며, 디스크의 소스 코드나 SDK 종속성을 수정하지 않습니다. 컴파일 과정에서 생성된 콜드 스타트 코드는 ft_sdk를 참조하므로 앱에 ft_sdk 런타임 종속성을 계속 유지해야 합니다. 설정을 완료한 후 클린 빌드를 한 번 실행하세요. 플러그인을 설치하지 않으면 console, hilog, 콜드 스타트 데이터가 자동으로 수집되지 않습니다.

SDK 추가¶

프로젝트 연동 방식에 따라 다음 설치 방법 중 하나를 선택할 수 있습니다.

방법 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 12 이상을 사용해야 합니다. ft_sdk_ext의 HttpInterceptorChain 기능은 HarmonyOS API 22 이상이 필요합니다.
프로젝트 루트의 build-profile.json5에서 실제 빌드 product에 대해 OHMUrl 정규화를 활성화합니다. 동일한 이름의 구성이 이미 있다면 strictMode 내용만 병합하면 됩니다:

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

oh-package.json5의 종속성 이름은 SDK 패키지 이름과 일치해야 합니다. 코드는 각 패키지의 공개 Index 진입점에서만 API를 임포트하고 src/main/... 같은 내부 경로는 사용하지 마세요.
Release 패키지는 ArkGuard 난독화가 활성화되어 있으며, HAR과 함께 배포되는 consumer 난독화 규칙을 통해 공개 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 자동 수집 기능이 필요할 때 설치합니다. 이 기능은 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 자동 수집의 임포트 진입점(HarmonyOS API 22 이상 필요)
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를 유지하면 됩니다

코드 임포트 변경¶