콘텐츠로 이동

문제 해결

컴파일 문제 해결

컴파일 과정에서 오류가 발생하면 먼저 컴파일 환경을 확인해야 합니다.

실행 가능한 컴파일 환경

✅ 실행 가능 환경

  • AGP com.android.tools.build:gradle 버전 3.5.0 이상
  • Gradle 버전 5.4.0 이상
  • Java 버전 8.0 이상
  • Android minSdkVersion 21

참고: Android Studio 버전이 업데이트됨에 따라 이 부분의 버전 호환성도 달라질 수 있습니다. 위 조건을 충족하는 컴파일 환경에서도 컴파일 오류가 계속 발생하면 개발자에게 문의하세요.

⚠️ 호환 실행 환경

  • AGP com.android.tools.build:gradle 버전 3.0.1 이상
  • Gradle 버전 4.8.1 이상
  • Java 버전 8.0 이상
  • Android minSdkVersion 21

이 환경에서는 ft-plugin을 사용할 수 없으며, 데이터 자동 수집 부분은 수동으로 통합하여 완료해야 합니다. 수동 통합에 대한 자세한 내용은 수동 통합을 참고하세요.

SDK import를 확인할 수 없음

위 오류는 Maven 저장소가 올바르게 설정되지 않아 발생합니다. 설정을 참고하세요.

컴파일 오류

Desugaring Error

>Task :app:transformClassesWithStackFramesFixerForDebug
    Exception in thread "main" java.lang.IllegalStateException: Expected a load for Ljava/lang/String; to set up parameter 0 for com/ft/sdk/FTRUMGlobalManager$$Lambda$11 but got 95
        at com.google.common.base.Preconditions.checkState (Preconditions.java:756)
        at com.google.devtools.build. android.desugar.LambdaDesugaring$InvokedynamicRewriter .attemptAllocationBeforeArgumentLoadsLambdaDesugaring.java:535)
        at com.google.devtools.build.android.desugar.LambdaDesugaring$InvokedynamicRewriter.visitInvokeDynamicInsn
        (LambdaDesugaring.java: 420)
        at org.objectweb.asm.ClassReader.a(Unknown Source)
        at org.objectweb.asm.ClassReader.b(Unknown Source)
        at org.objectweb.asm.ClassReader.accept(Unknown Source)
        at org.objectweb.asm.ClassReader.accept(Unknown Source)
        at com.google.devtools.build. android.desugar. Desugar.desugarClassesInInput (Desugar.java:401) at com.google.devtools.build.android.desugar.Desugar.desugar0neInput(Desugar.java:326) at com.google.devtools.build.android.desugar. Desugar.desugar (Desugar.java:280) at com.google.devtools.build.android.desugar. Desugar.main (Desugar.java:584)
컴파일 과정에서 위 오류가 발생하면 AGP 3.0.0 호환성 문제 때문입니다. 이슈에서 이 문제를 설명하고 있습니다. AGP를 3.1.0 이상으로 올리거나, 최신 버전 SDK를 사용하여 app/build.gradle에서 버전을 업그레이드하면 해결됩니다.

dependencies {
    implementation('com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.3.10.beta01')// 1.3.10 이상 사용 가능
    }

API 'android.registerTransform' is obsolete

AGP 7.0에서 Transform이 Deprecated로 표시되었고 AGP 8.0에서 더 이상 사용되지 않습니다. ft-plugin:1.2.0에서 이미 대응이 완료되었으므로 해당 버전으로 업그레이드하여 이 오류를 수정하세요. 자세한 내용은 통합 설정을 참고하세요.

AndroidComponentsExtension ClassNotFoundException

AndroidComponentsExtension은 AGP 7.4.2에서 지원하는 메서드입니다. 이 버전보다 낮은 컴파일 환경에서는 이 오류가 발생하므로 ft-plugin-legacy 버전을 사용하여 오류를 수정하세요. 자세한 내용은 통합 설정을 참고하세요.

java.lang.IllegalArgumentException:

  • Invalid opcode 169

ft_plugin_legacy 사용 중 이 오류가 발생하면 asm-commons:7.0 버전의 버그입니다. 원본 이슈는 여기에 있으며, plugin 설정에서 org.ow2.asm:asm-commons:7.2 이상 버전을 의존성으로 추가하여 이 문제를 해결하세요. ./gradlew buildEnvironment로 실제 사용 중인 asm-commons 버전을 확인할 수 있습니다.

buildscript {
    dependencies {
        classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
        // 의존성 추가
        classpath 'org.ow2.asm:asm-commons:7.2' 
    }
}
  • org.ow2.asm:asm 버전이 7.0 미만

현재 plugin 버전은 org.ow2.asm:asm7.x 이상 버전의 빌드 환경만 지원합니다. ./gradlew buildEnvironment로 빌드 환경을 조회하여 확인할 수 있습니다. 7.x 이상 버전을 강제 의존성으로 추가하여 수정할 수 있으며, 7.2 이상 사용을 권장합니다.

buildscript {
    dependencies {
        classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
        // 의존성 추가
        classpath 'org.ow2.asm:asm:7.2'
        classpath 'org.ow2.asm:asm-commons:7.2'
    }
}

SDK 초기화 오류 확인

Logcat에서 Level이 Error이고 Tag가 [FT-SDK] 접두사인 로그가 있는지 확인하세요

[FT-SDK] com.demo E 请先安装SDK(在应用启动时调用 FTSdk.install(FTSDKConfig ftSdkConfig))

Debug 디버깅 활성화

ft-sdk Debug 모드

다음 설정으로 SDK의 debug 기능을 활성화할 수 있습니다. 활성화하면 콘솔 Logcat에 SDK 디버그 로그가 출력됩니다. [FT-SDK] 문자열로 필터링하여 Guance SDK 로그를 찾을 수 있습니다.

  val config = FTSDKConfig.builder(datakitUrl).setDebug(true)
  FTSdk.install(config)

로그 예시

데이터 동기화
// 업로드 주소가 SDK 설정에 올바르게 반영되었는지 확인
[FT-SDK]FTHttpConfigManager com.demo D  serverUrl ==>
                                    Datakit Url:http://10.0.0.1:9529
// 다음은 연결 오류 로그
[FT-SDK]SyncTaskManager com.demo   E  Network not available Stop poll
[FT-SDK]SyncTaskManager com.demo   E  ↵
            1:Sync Fail-[code:10003,response:failed to connect to 10.0.0.1 (port 9529) from ↵
            10.0.2.16 (port 47968) after 10000ms,检查本地网络连接是否正常]

// 다음은 정상 동기화 로그
[FT-SDK]SyncTaskManager com.demo   D  Sync Success-[code:200,response:]

Release 버전 배포 시 이 설정을 비활성화하는 것이 좋습니다

ft-plugin Debug 모드

다음 설정으로 Plugin의 debug 로그를 활성화할 수 있습니다. 활성화하면 Build 출력 로그에서 [FT-Plugin] 출력 로그를 확인할 수 있습니다. 이를 통해 Plugin ASM 쓰기 상황을 확인하세요.

FTExt {
    // Plugin 로그 표시 여부, 기본값은 false
    showLog = true
}

Release 버전 배포 시 이 설정을 비활성화하는 것이 좋습니다

SDK 내부 로그를 캐시 파일로 변환

// >= 1.4.6
// 기본 경로: /data/data/{package_name}/files/LogInner.log
LogUtils.registerInnerLogCacheToFile()

// >= 1.4.5+ 
val cacheFile = File(filesDir, "LogCache.log")
LogUtils.registerInnerLogCacheToFile(cacheFile)

내부 로그의 완전성을 위해 SDK 초기화 전에 이 설정을 지정해야 합니다

Session Replay Compose 리플레이에서 순수 컨테이너 배경색 누락

Jetpack Compose Session Replay를 사용할 때 페이지에 레이아웃과 배경 그리기만을 위한 Row, Column, Box 등의 컨테이너가 있고, 예를 들어 Modifier.background(...)만 설정했으며 텍스트, 클릭, 시맨틱 또는 기타 접근성 정보가 없는 경우 해당 컨테이너는 Compose 시맨틱 노드 트리에 나타나지 않을 수 있습니다. Session Replay는 현재 시맨틱 노드를 기반으로 매핑하므로 리플레이에서 배경색이 누락되거나 Toolbar 또는 블록 배경이 기본 흰색으로 표시될 수 있습니다.

해당 배경이 리플레이 표시에 중요하다면 컨테이너에 빈 시맨틱 마커를 추가하여 시맨틱 노드 트리에 포함되도록 할 수 있습니다:

Row(
    modifier = Modifier
        .fillMaxWidth()
        .height(56.dp)
        .semantics { }
        .background(Color(0xFFFF6600))
)

이 방식은 UI 표시 효과를 변경하지 않으며 Session Replay가 해당 Compose 컨테이너 노드를 캡처하도록 돕기 위한 것입니다. 향후 SDK는 시맨틱이 없는 컨테이너 배경에 대한 자동 수집 기능을 지속적으로 강화할 예정입니다.

SDK가 정상적으로 실행되지만 데이터가 없음

  • Datakit 확인이 정상적으로 실행 중인지 확인하세요

  • SDK 업로드 주소 datakitUrl 또는 datawayUrl의 설정이 올바른지 확인하고 올바르게 초기화했는지 확인하세요. debug 모드에서 로그를 확인하여 업로드 문제를 판단하세요.

  • Datakit이 해당 워크스페이스로 데이터를 업로드하는지, 오프라인 상태인지 확인하세요. Guance에 로그인하여 「인프라」를 확인하면 이 문제를 확인할 수 있습니다.

OkHttp 3.12.+ 호환성 문제

ft-sdk < 1.6.13 버전에서 데이터 압축 FTSDKConfig.setCompressIntakeRequests(true)을 활성화하면 SDK 데이터 수집은 정상이지만 데이터 동기화 단계에서 오류 알림이 발생하지 않고 HTTP 상태 코드 로그도 출력되지 않습니다.

처리 방법: ft-sdk >= 1.6.13 버전을 사용하거나 OkHttp 4.5.0 이상 버전을 사용하면 이 문제를 해결할 수 있습니다

데이터 손실

일부 데이터 손실

  • RUM의 특정 Session 데이터 또는 Log, Trace의 일부 데이터가 손실된 경우 먼저 FTRUMConfig, FTLoggerConfig, FTTraceConfig에서 sampleRate < 1을 설정했는지 확인하여 가능성을 배제해야 합니다.
  • 데이터를 업로드하는 기기의 네트워크와 Datakit이 설치된 기기의 네트워크 및 부하 문제를 확인하세요.
  • FTSdk.shutDown을 올바르게 호출했는지 확인하세요. 이 메서드는 캐시된 데이터를 포함한 SDK 데이터 처리 객체를 해제합니다.

Resource 데이터 손실

자동 수집, ft-plugin을 올바르게 통합하지 않음

Resource 자동 수집은 Plugin ASM 바이트코드 주입을 통해 OkHttpClient Interceptor와 EventListener를 자동 설정하고 FTTraceInterceptor, FTResourceInterceptor, FTResourceEventListener.FTFactory를 주입합니다. Plugin을 사용하지 않는 경우 여기를 참고하세요.

사용자 정의 WebView 자동 수집이 적용되지 않음

네이티브 WebView 페이지 수집은 정상이지만 사용자 정의 WebView 페이지에서 예상한 자동 수집이 트리거되지 않으면 Plugin 로그를 통해 WebView 인식 문제인지 먼저 확인하는 것이 좋습니다.

확인 방법:

  1. 먼저 통합 설정을 참고하여 FTExt에서 로그를 활성화하세요:

    FTExt {
        showLog = true
        verboseLog = true
    }
    
  2. 다시 컴파일한 후 Build 로그에서 [FT-Plugin] 및 WEBVIEW 관련 출력을 검색하고, 다음과 유사한 로그가 나타나는지 중점적으로 확인하세요:

    [FT-Plugin]:TARGET_CUSTOM_WEBVIEW_METHOD-> owner:com/example/CustomWebView, class:com/example/WebViewActivity$2, super:java/lang/Object, method:loadUrl(Ljava/lang/String;)V | onItemSelected(Landroid/widget/AdapterView;Landroid/view/View;IJ)V
    

이러한 TARGET_CUSTOM_WEBVIEW_METHOD 로그가 나타나면 Plugin이 현재 owner를 사용자 정의 WebView로 인식하고 해당 호출을 처리했다는 의미입니다.

이러한 로그가 계속 나타나지 않지만 실제로 호출하는 대상이 비즈니스 사용자 정의 WebView라면 일반적으로 해당 클래스가 knownWebViewClasses에 추가되었는지 확인해야 합니다. 이는 자동 수집 인식에만 영향을 주는 것이 아니라 Plugin이 사용자 정의 WebView 내부 메서드를 일반 메서드로 간주하여 계속 ASM 주입을 수행하는지와도 관련됩니다. 올바르게 인식되지 않으면 런타임에 loadUrl 등의 메서드가 반복 호출되어 최종적으로 WebView 화면이 하얗게 표시되는 문제가 발생할 수 있습니다. 확인 시 다음과 유사한 로그도 계속 주의 깊게 살펴보세요:

knownWebviews.contains(owner) = false
owner: com/example/CustomWebView

이는 일반적으로 현재 클래스가 아직 Plugin에 의해 WebView로 인식되지 않았음을 의미합니다.

처리 방법:

FTExt에 knownWebViewClasses를 추가하고 실제 사용하는 사용자 정의 WebView 클래스를 설정에 포함하세요. 비즈니스의 WebView 기본 클래스를 먼저 추가하는 것이 좋습니다. 상속 계층이 깊은 경우 기본 클래스와 현재 사용 클래스를 함께 추가할 수 있습니다. 이렇게 하면 Plugin이 WebView 호출을 올바르게 인식할 수 있고 사용자 정의 WebView 내부 메서드가 ASM에 중복 주입되는 것도 방지할 수 있습니다.

FTExt {
    showLog = true
    verboseLog = true
    knownWebViewClasses = [
        'com.example.web.BaseWebView',
        'com.example.web.CustomWebView'
    ]
}

knownWebViewClasses의 역할은 비즈니스 사용자 정의 WebView를 미리 Plugin의 알려진 WebView 목록에 추가하는 것입니다. 이렇게 하면 사용자 정의 WebView 인식 문제를 해결하고, Plugin이 WebView 내부 메서드의 중복 주입을 건너뛰도록 하여 런타임 반복 호출과 화면이 하얗게 표시되는 문제를 방지할 수 있습니다.

OkHttpClient.build() 설정 문제

Plugin ASM은 애플리케이션이 OkHttpClient.Builder().build()를 호출할 때 네트워크 수집 기능을 자동으로 주입합니다. 다음 두 가지 경우 네트워크 수집이 실패할 수 있습니다:

  1. 타이밍 문제 - SDK 초기화 미완료. SDK 초기화가 완료되기 전에 OkHttpClient.Builder().build()를 호출하면 빈 설정이 로드되어 Resource 관련 데이터가 손실될 수 있습니다. 디버그 로그를 확인하여 초기화 순서가 올바른지 확인할 수 있습니다.
  2. 생성 방식 문제. 표준 OkHttpClient.Builder().build() 메서드를 사용하지 않고 OkHttpClient 객체를 생성한 경우입니다. 예를 들어 OkHttpClient를 직접 인스턴스화하거나 다른 빌드 방식을 사용한 경우입니다.
// SDK 초기화 로그
[FT-SDK]FTSdk   com.ft  D  initFTConfig complete
[FT-SDK]FTSdk   com.ft  D  initLogWithConfig complete
[FT-SDK]FTSdk   com.ft  D  initRUMWithConfig complete
[FT-SDK]FTSdk   com.ft  D  initTraceWithConfig complete

// SDK OkHttpClient.Builder.build() 호출 시 출력되는 로그
// (SDK 초기화 이후에 호출되어야 함)
[FT-SDK]AutoTrack   com.ft  D  trackOkHttpBuilder    

초기화 호출 순서를 조정할 수 없다면 수동 방식으로 통합할 수 있습니다.

Interceptor 또는 EventListener로 데이터를 2차 처리한 경우

Plugin ASM이 주입된 후 원본 프로젝트 코드를 기반으로 OkHttpClient.Builder()에 addInterceptor를 추가하고, 각각 FTTraceInterceptor와 FTResourceInterceptor를 추가합니다. 여기서는 HTTP 요청의 body contentLength를 사용하여 고유 ID 계산에 참여하며, Resource 데이터의 각 단계 데이터는 이 ID를 통해 컨텍스트로 연결됩니다. 따라서 통합하는 쪽에서 OkHttp를 사용할 때 addInterceptor도 추가하고 데이터를 2차 처리하여 크기가 변경되면 ID의 각 단계 계산이 일치하지 않게 되어 데이터가 손실될 수 있습니다.

처리 방법:

ft-sdk < 1.4.1

사용자 정의 addInterceptor 위치 순서를 통해 SDK 메서드가 가장 먼저 ID를 계산하도록 하면 이 문제를 해결할 수 있습니다. 중복 설정을 피하려면 사용자 정의 방식에서는 FTRUMConfig의 enableTraceUserResource, FTTraceConfig의 enableAutoTrace 설정을 비활성화해야 합니다.

ft-sdk >= 1.4.1

SDK가 수동 설정이 아닌 시나리오에서는 이 문제에 대한 호환성을 자체적으로 적용합니다. 이미 수동 설정을 진행한 경우 Interceptor가 앞쪽에 위치하도록 해야 합니다.

OkHttp 3.12.+ 호환성 문제

ft-sdk < 1.6.13 사용하는 Interceptor가 response body 내용을 읽는 경우 현재 Resource 데이터를 수집하지 못할 수 있습니다.

처리 방법:

ft-sdk < 1.6.13

  1. OkHttp 버전을 변경하지 않고 수동 설정으로 이 문제를 해결하세요

    OkHttpClient.Builder builder = new OkHttpClient.Builder()
        .addInterceptor(new CustomReadReponseInterceptor())// 응답 body 읽기
        .addInterceptor(new FTTraceInterceptor())
        .addInterceptor(new FTResourceInterceptor())
        .addInterceptor(new CustomRequestBodyFixInterceptor())// 암호화 또는 body 수정 포함
        .eventListenerFactory(new FTResourceEventListener.FTFactory());
    
    OkHttpClient client = builder.build();
    
  2. OkHttp를 4.5.0 이상 버전으로 업그레이드해도 이 문제를 해결할 수 있습니다.

ft-sdk >= 1.6.13

SDK가 수동 설정이 아닌 시나리오에서는 이 문제에 대한 호환성을 자체적으로 적용합니다.

Error 데이터 손실 - Crash 유형 데이터

  • Crash 캡처 기능이 있는 다른 타사 SDK를 함께 사용 중인지 확인하고, 그런 경우 SDK 초기화 메서드를 다른 SDK 뒤에 배치해야 합니다.

특정 필드 정보 손실

사용자 데이터 필드

  • 사용자 데이터 바인딩 메서드를 올바르게 호출했는지 확인하세요. debug 모드에서는 log를 통해 이 문제를 추적할 수 있습니다.

    [FT-SDK]FTRUMConfigManager com.demo D  bindUserData xxxx
    
    ///---> 사용자 데이터 작업 <-----
    
    [FT-SDK]FTRUMConfigManager com.demo D unbindUserData
    

사용자 정의 파라미터 손실 또는 값 오류

  • 올바른 시나리오에서 호출했는지 확인하세요. FTRUMConfig.addGlobalContext, FTLoggerConfig.addGlobalContext는 애플리케이션 주기 내에서 변경되지 않는 시나리오에 적합합니다. 예를 들어 앱 채널 제공자, 앱의 서로 다른 Flavor 속성 등의 데이터입니다. 동적 시나리오에 따라 실시간으로 대응해야 하는 경우 RUM 및 Log 인터페이스를 수동으로 호출해야 합니다.
  • debug 모드에서 [FT-SDK]SyncTaskManager 로그를 확인하세요. 이 로그를 통해 사용자 정의 필드 파라미터의 정확성을 검증할 수 있습니다.

로그에서 enableConsoleLog 활성화 시 지연 문제

지연이 발생하는 경우 로그 수집 데이터가 너무 큰 것이 원인일 수 있습니다. FTLoggerConfig.enableConsoleLog의 원리는 android.util.Log, Java 및 Kotlin println을 캡처하는 것입니다. 필요에 따라 FTLoggerConfig 설정의 sampleRate, logPrefix, logLevelFilters 파라미터를 조정하여 이 문제를 제거하거나 완화하는 것이 좋습니다.

OkHttp EventListener가 SDK 통합 후 작동하지 않음

Plugin AOP ASM이 주입된 후 원본 프로젝트 코드를 기반으로 OkHttpClient.Builder()에 eventListenerFactory를 추가하며, 이는 기존 eventListener 또는 eventListenerFactory를 덮어씁니다.

처리 방법:

ft-sdk < 1.4.1

Plugin AOP 자동 설정을 비활성화하고 FTRUMConfig setEnableTraceUserResource(false)를 설정합니다. 동시에 CustomEventListenerFactory를 사용자 정의하여 FTResourceEventListener.FTFactory를 상속하고, 사용자 정의 방식으로 통합합니다.

ft-sdk >= 1.4.1

CustomEventListenerFactory를 사용자 정의하여 FTResourceEventListener.FTFactory를 상속하고, FTRUMConfig.setOkHttpEventListenerHandler를 설정하여 ASM이 주입한 eventListenerFactory를 사용자 정의합니다.

ft-sdk >= 1.6.7

SDK가 수동 설정이 아닌 시나리오에서는 이 문제에 대한 호환성을 자체적으로 적용합니다.

TraceID 손실 또는 Trace Propagation Header와 불일치

전체 요청 데이터를 수집할 때 일반적으로 Interceptor와 EventListener에서 각각 정보를 가져와야 합니다. 이 두 부분의 데이터를 효과적으로 연관시키기 위해 SDK는 고유 ID를 사용하여 동일한 네트워크 요청을 연결합니다. 그러나 1.6.10 버전 이전에는 동일한 요청에서 이 ID가 동일하여 높은 동시성 시나리오에서 데이터가 뒤섞이거나 손실될 수 있었습니다. 1.6.10 버전부터 FTSDKConfig.setEnableOkhttpRequestTag(true)를 호출하거나 Request에 ResourceID를 명시적으로 추가하여 각 요청에 고유 식별자를 구분할 수 있으므로 동일한 요청 간의 간섭 문제를 피할 수 있습니다. 설정 방법은 여기를 참고하세요.

문서 평가

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