Android 앱 연동¶
Android 앱의 메트릭 데이터를 수집하여 앱 성능을 시각적으로 분석합니다.
읽기 경로¶
- 최초 연동: 먼저 연동 방식 선택을 확인합니다. 수동 연동은 빠른 시작을 참고할 수 있습니다.
- 전체 연동: 이 문서를 계속 읽습니다.
- 파라미터 상세: SDK 초기화, RUM 설정, Log 설정, Trace 설정을 확인합니다.
- 고급 기능: “고급 시나리오” 그룹의 전용 페이지를 확인합니다.
- 문제 해결: 문제 해결을 확인합니다.
사전 조건¶
주의
RUM Headless 서비스가 이미 활성화되어 있다면 사전 조건이 자동으로 구성되므로 앱을 바로 연동할 수 있습니다.
로컬 환경 배포를 사용하는 경우 다음 데이터 수신 측 구성을 완료해야 합니다. 퍼블릭 DataWay를 사용하는 경우 DataKit을 직접 배포할 필요가 없습니다.
- DataKit을 설치합니다.
- RUM 수집기를 구성합니다.
- DataKit을 퍼블릭 네트워크에서 액세스할 수 있도록 구성하고 IP 지리 정보 라이브러리를 설치합니다.
앱 연동¶
- RUM > 앱 생성 > Android로 이동합니다.
- 앱 이름을 입력합니다.
- 앱 ID를 입력합니다.
- 「연동 방식 선택」에서 Agent 자동 연동 또는 수동 연동을 선택한 후 「연동 구성」을 완료합니다.
연동 방식 선택¶
앱 구성 페이지에서 「Agent 자동 연동」 또는 「수동 연동」을 선택한 후 「연동 구성」을 완료합니다. 이미 앱이 있는 경우 구성 페이지로 바로 이동하여 연동을 계속할 수 있습니다.
| 연동 방식 | 사용 사례 | 작업 진입점 |
|---|---|---|
| Agent 자동 연동 | 코딩 어시스턴트가 프로젝트를 분석하고 SDK 연동을 완료하도록 하려는 경우 | 콘솔에서 생성된 프롬프트를 복사하여 앱 코드 저장소에서 코딩 어시스턴트에 전달해 실행합니다. |
| 수동 연동 | SDK를 직접 설치하고 파라미터를 구성하려는 경우 | 데이터 보고 방식을 확인한 후 이 문서와 빠른 시작에 따라 구성을 완료합니다. |
Agent 자동 연동¶
- 현재 앱의 구성 페이지에서 「Agent 자동 연동」을 선택합니다.
- 「연동 구성」의 전체 프롬프트를 복사하고, 현재 앱의 연동 정보가 사용되는지 확인합니다.
- 앱 코드 저장소에서 코딩 어시스턴트를 열고 프롬프트를 붙여넣으면 Agent가 연동 가이드에 따라 프로젝트를 분석하고 SDK 구성을 완료합니다.
- 앱을 빌드하고 실행하여 페이지 방문 등의 작업을 트리거한 후 현재 앱의 탐색기에서 데이터가 수신되었는지 확인합니다.
페이지에 개인 API Key 또는 임시 인증 코드가 준비되지 않았다는 메시지가 표시되면 안내에 따라 보완한 후 프롬프트를 다시 복사하세요.
수동 연동¶
앱 구성 페이지에서 「수동 연동」을 선택하고 데이터 보고 방식을 확인합니다.
- 퍼블릭 DataWay: RUM 데이터를 직접 수신하며 DataKit 수집기를 설치할 필요가 없습니다.
- 로컬 환경 배포: 사전 조건을 충족한 후 RUM 데이터를 수신합니다.
아래 설치 및 빠른 시작에 따라 SDK 설치, 초기화 및 검증을 완료합니다. 기존 SDK 구성이 있는 경우 먼저 확인한 후 재사용하여 중복 초기화를 피해야 합니다.
설치¶
소스 코드 주소: https://github.com/GuanceCloud/datakit-android
데모: https://github.com/GuanceDemo/guance-app-demo
Gradle 구성¶
Plugin 추가¶
- 프로젝트 루트 디렉터리의
build.gradle파일에SDK원격 저장소 주소를 추가합니다.
//build.gradle
buildscript {
//...
repositories {
//...
// Plugin 원격 저장소 주소 추가
maven {
url 'https://mvnrepo.guance.com/repository/maven-releases'
}
}
dependencies {
//...
// Plugin 플러그인 추가, AGP 7.4.2 이상, Gradle 7.2.0 이상 필요
classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin:[latest_version]'
// AGP 7.4.2 미만 버전은 ft-plugin-legacy를 사용하세요.
//classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[latest_version]'
}
}
//setting.gradle
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
// Plugin 원격 저장소 주소 추가
maven {
url('https://mvnrepo.guance.com/repository/maven-releases')
}
}
}
//build.gradle
plugins{
// Plugin 플러그인 추가, AGP 7.4.2 이상, Gradle 7.2.0 이상 필요
id 'com.cloudcare.ft.mobile.sdk.tracker.plugin' version '[latest_version]' apply false
// AGP 7.4.2 미만 버전은 ft-plugin-legacy를 사용하세요.
//id 'com.cloudcare.ft.mobile.sdk.tracker.plugin.legacy' version '[latest_version]' apply false
}
- 프로젝트 메인 모듈의
app/build.gradle파일에Plugin사용을 추가합니다.
// app/build.gradle에서 플러그인을 적용합니다. 구성이 누락되면 아래 자동 수집 기능에 영향을 줍니다.
//
// 1. RUM: App 시작, OkHttp 요청, 필요 시 활성화되는 HTTP/HTTPS URLConnection 요청, WebView 활동 Activity/Fragment 전환, 클릭 이벤트
// 2. Log: Console Logcat
apply plugin: 'ft-plugin' //ft-plugin-legacy를 사용하는 경우에도 동일한 구성을 사용합니다.
//선택 사항: 필요에 따라 플러그인 파라미터 구성
FTExt {
//showLog = true
//asmVersion='asm7'
//ignorePackages=['com.ft','com/ft']
//knownWebViewClasses = ['com.your.CustomWebView']
}
플러그인 파라미터는 모두 선택 사항입니다. 대부분의 경우 apply plugin: 'ft-plugin'만으로 충분하며, 플러그인 동작을 디버깅하거나, 계측 범위를 제어하거나, WebView 인식을 수동으로 보완할 때만 FTExt 구성을 추가하면 됩니다.
| 파라미터 이름 | 유형 | 기본값 | 설명 | 사용 사례 |
|---|---|---|---|---|
| showLog | Boolean | false |
ft-plugin 빌드 로그를 출력할지 여부입니다. |
플러그인 실행 과정을 디버깅하거나 계측이 적용되었는지 확인할 때 활성화합니다. |
| asmVersion | String | asm9 |
플러그인에서 사용할 ASM 버전을 지정하며 asm7 ~ asm9를 선택할 수 있습니다. |
프로젝트의 다른 바이트코드 처리 플러그인과 호환성 요구 사항이 있을 때 조정합니다. |
| ignorePackages | String[] | 비어 있음 | ASM 계측을 수행하지 않을 패키지 경로를 구성합니다. 경로 구분 기호로 . 또는 /를 사용할 수 있습니다. |
일부 비즈니스 패키지, 서드파티 패키지 또는 다른 플러그인과 충돌하는 코드를 건너뛰어야 할 때 사용합니다. |
| instrumentHttpURLConnection | Boolean | true |
URL.openConnection() / openConnection(Proxy)의 반환값에 계측을 수행할지 여부입니다. ft-plugin >= 1.3.9-alpha01에서 지원하며 ft-sdk >= 1.7.6-alpha03이 필요합니다. |
URLConnection 계측을 비활성화해야 할 때 false로 설정합니다. 실제 수집을 위해서는 두 개의 RUM 스위치도 활성화해야 하며, 자세한 내용은 URLConnection 자동 수집을 참고하세요. |
| knownWebViewClasses | String[] | 비어 있음 | WebView로 인식해야 하는 사용자 정의 클래스를 수동으로 선언합니다. | 사용자 정의 WebView의 상속 계층이 복잡하여 자동 인식이 적용되지 않을 때 사용합니다. |
knownWebViewClasses는 자동 인식이 실패한 경우에만 구성하면 됩니다. 관련 문제 해결 방법은 사용자 정의 WebView 자동 수집이 적용되지 않는 경우를 참고하세요.
SDK 추가¶
- 프로젝트 루트 디렉터리의
build.gradle파일에SDK원격 저장소 주소를 추가합니다.
- 프로젝트 메인 모듈의
app/build.gradle파일에SDK의존성을 추가합니다.
//app/build.gradle
dependencies {
// SDK 의존성 추가
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:[latest_version]'
// 네이티브 계층 크래시 정보를 캡처하기 위한 의존성으로, ft-sdk와 함께 사용해야 하며 단독으로 사용할 수 없습니다.
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:[latest_version]'
// JSON 직렬화
implementation 'com.google.code.gson:gson:2.8.+'
// 선택 사항: OkHttp 네트워크 요청 자동 수집 및 자동 분산 추적을 사용할 때 추가하며, 최소 3.12.+ 이상 버전과 호환됩니다.
implementation 'com.squareup.okhttp3:okhttp:4.+'
}
최신 버전은 위의
ft-sdk,ft-plugin,ft-native버전 이름을 참고하세요.
Application 구성¶
SDK 초기화에 가장 적합한 위치는 Application의 onCreate 메서드입니다. 앱에 아직 Application이 없다면 이를 생성하고 AndroidManifest.xml에서 선언해야 합니다. 예시는 여기를 참고하세요.
R8 / Proguard 난독화 구성¶
ft-sdk 1.6.15 이전 버전을 사용하고 android.buildTypes에서 minifyEnabled = true를 설정해야 한다면 다음 구성을 활성화해야 합니다.
-dontwarn com.ft.sdk.**
### ft-sdk 라이브러리
-keep class com.ft.sdk.**{*;}
### ft-native 라이브러리
-keep class ftnative.*{*;}
### Action 수집 시 action_name의 클래스 이름이 난독화되지 않도록 방지###
-keepnames class * extends android.view.View
-keepnames class * extends android.view.MenuItem
초기화 설명¶
최소 초기화 예시는 빠른 시작을 참고하세요.
전체 FTSDKConfig 파라미터 설명은 SDK 초기화를 참고하세요.
상세 구성 진입점¶
고급 시나리오¶
- 사용자 정의 태그
- 사용자 정의 수집 규칙
- 데이터 수집 마스킹
- WebView 모니터링
- 방문자 식별자 Visitor ID
- 동적 구성 및 동적 업데이트 주소
- 심볼 파일 업로드
- 개인정보 보호 및 권한 설명
- Content Provider 설정
- 수동 호환 연동
Plugin AOP 무시¶
Plugin AOP가 오버라이드한 메서드에 @IgnoreAOP를 추가하여 ASM 삽입을 무시합니다. 일괄적으로 무시해야 하는 경우 ft-plugin FTExt의 ignorePackages를 사용하여 무시하세요.
자주 묻는 질문¶
전역 변수 추가 시 필드 충돌 방지¶
사용자 정의 필드와 SDK 데이터 간 충돌을 방지하려면 태그 이름에 프로젝트 약어 접두사를 추가하는 것이 좋습니다. 예: custom_tag_name. 프로젝트에서 사용하는 key 값은 소스 코드에서 확인할 수 있습니다. SDK 전역 변수에 RUM, Log와 동일한 변수가 있으면 RUM, Log가 SDK의 전역 변수를 덮어씁니다.
SDK 호환성¶
앱 마켓 개인정보 심사 대응¶
자세한 내용은 개인정보 보호 및 권한 설명을 참고하세요.
서드파티 프레임워크¶
flutter, react-native, uni-app, unity는 위의 네이티브 Android와 유사한 지연 초기화 방식을 사용하여 앱 마켓의 개인정보 심사에 대응할 수 있습니다.
Jetpack Compose 지원¶
현재 Compose 컴포넌트가 생성한 페이지의 자동 수집은 지원하지 않지만, 수동 Action 및 View 사용자 정의 인터페이스를 통해 클릭 이벤트와 페이지 전환 이벤트를 추적할 수 있습니다. 예시는 여기를 참고하세요.