Android 애플리케이션 연결¶

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

읽기 경로¶

처음 연결: 빠른 시작을 먼저 확인하세요.
전체 연결: 이 문서를 계속 읽으세요.
파라미터 상세: SDK 초기화, RUM 구성, Log 구성, Trace 구성을 확인하세요.
고급 기능: "고급 시나리오" 그룹의 전용 페이지를 확인하세요.
문제 해결: 문제 해결을 확인하세요.

사전 조건¶

참고

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

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

애플리케이션 연결¶

RUM > 애플리케이션 생성 > Android로 이동합니다.
애플리케이션 이름을 입력합니다.
애플리케이션 ID를 입력합니다.
애플리케이션 연결 방식을 선택합니다.
- 공용 네트워크 DataWay: DataKit 수집기 설치 없이 RUM 데이터를 직접 수신합니다.
- 로컬 환경 배포: 사전 조건을 충족한 후 RUM 데이터를 수신합니다.

설치¶

소스 코드 주소: https://github.com/GuanceCloud/datakit-android

데모: https://github.com/GuanceDemo/guance-app-demo

Gradle 구성¶

Plugin 적용¶

프로젝트 루트 디렉터리의 build.gradle 파일에 SDK의 원격 저장소 주소를 추가합니다.

buildscriptplugins DSL

//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: 앱 시작, OkHttp 요청, 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 계측을 수행하지 않을 패키지 경로를 구성합니다. 경로 구분자는 `.` 또는 `/`를 사용할 수 있습니다.	특정 비즈니스 패키지, 타사 패키지를 건너뛰거나 다른 플러그인과 충돌하는 코드를 피해야 할 때 사용합니다.
knownWebViewClasses	String[]	비어 있음	WebView로 인식해야 할 사용자 정의 클래스를 수동으로 선언합니다.	사용자 정의 WebView 상속 계층이 복잡하여 자동 인식이 작동하지 않을 때 사용합니다.

knownWebViewClasses는 자동 인식이 실패한 경우에만 구성이 필요합니다. 관련 문제 해결 방법은 사용자 정의 WebView 자동 수집이 작동하지 않음을 참조하세요.

SDK 적용¶

프로젝트 루트 디렉터리의 build.gradle 파일에 SDK의 원격 저장소 주소를 추가합니다.

buildscriptplugins DSL

//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.+'
    //선택 사항, 네트워크 요청 자동 수집 및 자동 링크 활성화에 필요, 최소 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를 사용하여 무시하세요.

JavaKotlin

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

}); ```

```kotlin 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 사용자 정의 인터페이스를 통해 클릭 이벤트와 페이지 전환 이벤트를 추적할 수 있습니다. 예제는 여기를 참조하세요.