콘텐츠로 이동

Android 앱 연동


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

읽기 경로

사전 조건

주의

RUM Headless 서비스가 이미 활성화되어 있다면 사전 조건이 자동으로 구성되므로 앱을 바로 연동할 수 있습니다.

로컬 환경 배포를 사용하는 경우 다음 데이터 수신 측 구성을 완료해야 합니다. 퍼블릭 DataWay를 사용하는 경우 DataKit을 직접 배포할 필요가 없습니다.

앱 연동

  1. RUM > 앱 생성 > Android로 이동합니다.
  2. 앱 이름을 입력합니다.
  3. 앱 ID를 입력합니다.
  4. 「연동 방식 선택」에서 Agent 자동 연동 또는 수동 연동을 선택한 후 「연동 구성」을 완료합니다.

연동 방식 선택

앱 구성 페이지에서 「Agent 자동 연동」 또는 「수동 연동」을 선택한 후 「연동 구성」을 완료합니다. 이미 앱이 있는 경우 구성 페이지로 바로 이동하여 연동을 계속할 수 있습니다.

연동 방식 사용 사례 작업 진입점
Agent 자동 연동 코딩 어시스턴트가 프로젝트를 분석하고 SDK 연동을 완료하도록 하려는 경우 콘솔에서 생성된 프롬프트를 복사하여 앱 코드 저장소에서 코딩 어시스턴트에 전달해 실행합니다.
수동 연동 SDK를 직접 설치하고 파라미터를 구성하려는 경우 데이터 보고 방식을 확인한 후 이 문서와 빠른 시작에 따라 구성을 완료합니다.

Agent 자동 연동

  1. 현재 앱의 구성 페이지에서 「Agent 자동 연동」을 선택합니다.
  2. 「연동 구성」의 전체 프롬프트를 복사하고, 현재 앱의 연동 정보가 사용되는지 확인합니다.
  3. 앱 코드 저장소에서 코딩 어시스턴트를 열고 프롬프트를 붙여넣으면 Agent가 연동 가이드에 따라 프로젝트를 분석하고 SDK 구성을 완료합니다.
  4. 앱을 빌드하고 실행하여 페이지 방문 등의 작업을 트리거한 후 현재 앱의 탐색기에서 데이터가 수신되었는지 확인합니다.

페이지에 개인 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 원격 저장소 주소를 추가합니다.
//build.gradle
allprojects {
    repositories {
        //...
        // SDK 원격 저장소 주소 추가
        maven {
            url 'https://mvnrepo.guance.com/repository/maven-releases'
            }
    }
}
//build.gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        // SDK 원격 저장소 주소 추가
        maven {
            url('https://mvnrepo.guance.com/repository/maven-releases')
            }
    }
}
  • 프로젝트 메인 모듈의 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에서 선언해야 합니다. 예시는 여기를 참고하세요.

<application 
       android:name="YourApplication"> 
</application> 

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 초기화를 참고하세요.

상세 구성 진입점

고급 시나리오

Plugin AOP 무시

Plugin AOP가 오버라이드한 메서드에 @IgnoreAOP를 추가하여 ASM 삽입을 무시합니다. 일괄적으로 무시해야 하는 경우 ft-plugin FTExt의 ignorePackages를 사용하여 무시하세요.

View.setOnClickListener(new View.OnClickListener() {
    @Override
    @IgnoreAOP
    public void onClick(View v) {

    }
});
View.setOnClickListener @IgnoreAOP {

}

자주 묻는 질문

전역 변수 추가 시 필드 충돌 방지

사용자 정의 필드와 SDK 데이터 간 충돌을 방지하려면 태그 이름에 프로젝트 약어 접두사를 추가하는 것이 좋습니다. 예: custom_tag_name. 프로젝트에서 사용하는 key 값은 소스 코드에서 확인할 수 있습니다. SDK 전역 변수에 RUM, Log와 동일한 변수가 있으면 RUM, Log가 SDK의 전역 변수를 덮어씁니다.

SDK 호환성

앱 마켓 개인정보 심사 대응

자세한 내용은 개인정보 보호 및 권한 설명을 참고하세요.

서드파티 프레임워크

flutter, react-native, uni-app, unity는 위의 네이티브 Android와 유사한 지연 초기화 방식을 사용하여 앱 마켓의 개인정보 심사에 대응할 수 있습니다.

Jetpack Compose 지원

현재 Compose 컴포넌트가 생성한 페이지의 자동 수집은 지원하지 않지만, 수동 Action 및 View 사용자 정의 인터페이스를 통해 클릭 이벤트와 페이지 전환 이벤트를 추적할 수 있습니다. 예시는 여기를 참고하세요.

문서 평가

이 페이지가 도움이 되었나요?