Troubleshooting¶

Compilation Troubleshooting¶

If errors occur during the compilation process, first check the compilation environment.

Runnable Compilation Environment¶

✅ Runnable Environment¶

AGP com.android.tools.build:gradle version 3.5.0 or higher
Gradle version 5.4.0 or higher
Java version 8.0 or higher
Android minSdkVersion 21

Note: As Android Studio versions update, this version compatibility may also change. If your compilation environment meets the above conditions but you still encounter compilation errors, please contact our developers.

⚠️ Compatible Runtime Environment¶

AGP com.android.tools.build:gradle version 3.0.1 or higher
Gradle version 4.8.1 or higher
Java version 8.0 or higher
Android minSdkVersion 21

In this environment, ft-plugin cannot be used. The automatic data capture part needs to be integrated manually. For more details on manual integration, refer to Manual Integration.

SDK Import Cannot Be Resolved¶

The above errors occur because the maven repository is not set correctly. Please refer to the configuration here.

Compilation Errors¶

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)

If the above error occurs during compilation, it is caused by a compatibility issue with AGP 3.0.0. This issue explains the problem. You can resolve it by upgrading AGP to version 3.1.0 or higher, or by using a newer version of the SDK. Upgrade the version in app/build.gradle.

dependencies {
    implementation('com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.3.10.beta01')//Versions 1.3.10 and above are acceptable.
}

API 'android.registerTransform' is obsolete¶

Transform has been marked as Deprecated in AGP 7.0 and is deprecated in AGP 8.0. ft-plugin:1.2.0 has been adapted accordingly. Please upgrade to the corresponding version to fix this error. For specific instructions, see Integration Configuration.

AndroidComponentsExtension ClassNotFoundException¶

AndroidComponentsExtension is a method supported by AGP 7.4.2. Compilation environments below this version will generate this error. You can use the ft-plugin-legacy version to fix this error. For specific instructions, see Integration Configuration.

java.lang.IllegalArgumentException:¶

Invalid opcode 169

If this error occurs while using ft_plugin_legacy, it is a bug in the asm-commons:7.0 version. The original issue is here. Resolve this issue by depending on org.ow2.asm:asm-commons:7.2 or higher in the plugin configuration. You can confirm the actual asm-commons version used by running ./gradlew buildEnvironment.

buildscript {
    dependencies {
        classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
        // Add dependency
        classpath 'org.ow2.asm:asm-commons:7.2'
    }
}

org.ow2.asm:asm version lower than 7.0

Currently, the plugin version only supports build environments using org.ow2.asm:asm7.x or higher. Query the build environment via ./gradlew buildEnvironment to confirm. You can fix this by forcing a dependency on version 7.x or higher. It is recommended to use version 7.2 or higher.

buildscript {
    dependencies {
        classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
         // Add dependency
        classpath 'org.ow2.asm:asm:7.2'
        classpath 'org.ow2.asm:asm-commons:7.2'
    }
}

SDK Initialization Exception Verification¶

Check Logcat to see if there are logs with Level Error and Tag prefixed with [FT-SDK].

[FT-SDK] com.demo E Please install the SDK first (call FTSdk.install(FTSDKConfig ftSdkConfig) at application startup)

Enable Debug Mode¶

Historical Compatibility Anchor¶

ft-sdk Debug Mode¶

You can enable the SDK's debug function with the following configuration. After enabling, the console LogCat will output SDK debug logs. You can filter for the [FT-SDK] string to locate the TrueWatch SDK logs.

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

Log Examples¶

Data Synchronization¶

//Check if the upload address is correctly entered into the SDK configuration.
[FT-SDK]FTHttpConfigManager com.demo D  serverUrl ==>
                                    Datakit Url:http://10.0.0.1:9529
//The following are connection error logs.
[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,Check if the local network connection is normal.]

//The following are normal synchronization logs.
[FT-SDK]SyncTaskManager com.demo   D  Sync Success-[code:200,response:]

It is recommended to turn off this configuration when releasing the Release version.

ft-plugin Debug Mode¶

You can enable Plugin debug logs with the following configuration. After enabling, you can find the [FT-Plugin] output logs in the Build output logs. Use this to view the Plugin ASM write status.

FTExt {
    //Whether to display Plugin logs, default is false.
    showLog = true
}

It is recommended to turn off this configuration when releasing the Release version.

Convert SDK Internal Logs to Cache Files¶

// >= 1.4.6
// Default path: /data/data/{package_name}/files/LogInner.log
LogUtils.registerInnerLogCacheToFile()

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

To ensure the integrity of internal logs, this configuration must be set before SDK initialization.

Session Replay Compose Playback Missing Pure Container Background Color¶

When using Jetpack Compose Session Replay, if a page contains containers like Row, Column, or Box used only for layout and background drawing, for example, only Modifier.background(...) is set, but there is no text, click, semantics, or other accessibility information, this container may not appear in the Compose semantic node tree. Session Replay currently maps based on semantic nodes, so the background color may be missing in the playback, and Toolbar or block backgrounds may appear as default white.

If this background is important for playback display, you can add an empty semantic marker to the container to include it in the semantic node tree:

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

This method does not change the interface display effect and is only used to help Session Replay capture this Compose container node. Subsequent SDK versions will continue to enhance the automatic capture capability for container backgrounds without semantics.

SDK Runs Normally But No Data¶

Check if Datakit is running normally.
Confirm that the SDK upload addresses datakitUrl or datawayUrl are configured correctly and initialized correctly. In debug mode, check the logs to diagnose upload issues.
Check if datakit is uploading data to the corresponding workspace and if it is offline. This can be confirmed by logging into TrueWatch and checking "Infrastructure".

Compatibility Issue with OKhttp 3.12.+¶

In ft-sdk < 1.6.13, if data compression FTSDKConfig.setCompressIntakeRequests(true) is enabled, SDK data collection works normally, but no error prompts or HTTP status code logs are output during the data synchronization phase.

Solution: Using ft-sdk >= 1.6.13 or okhttp 4.5.0 and above can resolve this issue.

Data Loss¶

Partial Data Loss¶

If RUM data for a particular Session or a few Log or Trace data points are missing, first check if sampleRate < 1 is set in FTRUMConfig, FTLoggerConfig, or FTTraceConfig.
Check the network of the device uploading data and the network and load of the device where datakit is installed.
Confirm that FTSdk.shutDown is called correctly. This method releases the SDK data processing objects, including cached data.

Resource Data Loss¶

Automatic Collection, ft-plugin Not Correctly Integrated¶

Automatic Resource collection relies on Plugin ASM bytecode writing to automatically set up Interceptor and EventListener for OkHttpClient, writing FTTraceInterceptor, FTResourceInterceptor, and FTResourceEventListener.FTFactory. If Plugin is not used, please refer to here.

Custom WebView Automatic Collection Not Taking Effect¶

If native WebView page collection works normally, but custom WebView pages do not trigger the expected automatic collection, it is recommended to first locate whether it is a WebView identification issue through Plugin logs.

Location Method:

First, refer to Integration Configuration to enable logs in FTExt:

FTExt {
    showLog = true
    verboseLog = true
}

After recompiling, search for [FT-Plugin] and WEBVIEW related output in the Build logs, focusing on whether logs similar to the following appear:

[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

If such TARGET_CUSTOM_WEBVIEW_METHOD logs appear, it means Plugin has identified the current owner as a custom WebView and processed the corresponding calls.

If no such logs are hit, but the actual calls are to business custom WebViews, you usually need to check if the class has been added to knownWebViewClasses. This not only affects automatic collection identification but also whether Plugin will treat the custom WebView's internal methods as ordinary methods for further ASM writing; if not correctly identified, runtime may experience loop calls to methods like loadUrl, ultimately manifesting as WebView white screen. During troubleshooting, you can also continue to watch for logs like:

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

This usually indicates that the current class has not been identified as a WebView by Plugin.

Solution:

Add knownWebViewClasses in FTExt to include the actual custom WebView classes used. It is recommended to add the business's WebView base class first; if the inheritance hierarchy is deep, you can add both the base class and the currently used class. This allows Plugin to correctly identify WebView calls and also avoids repeated ASM writing on custom WebView internal methods.

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

The role of knownWebViewClasses is to add business custom WebViews to Plugin's known WebView list in advance. This solves the custom WebView identification problem and also allows Plugin to skip repeated writing of WebView internal methods, avoiding runtime loop calls and white screens.

OkHttpClient.build() Setup Issue¶

Plugin ASM automatically injects network collection functionality when the application calls OkHttpClient.Builder().build(). The following two situations may cause network collection to fail:

Timing Issue - SDK Initialization Not Complete. If OkHttpClient.Builder().build() is called before SDK initialization is complete, it will load empty configuration, resulting in loss of Resource related data. Check debug logs to confirm if the initialization order is correct.
Creation Method Issue. Not using the standard OkHttpClient.Builder().build() method to create the OkHttpClient object, e.g., directly instantiating OkHttpClient or using other construction methods.

//SDK initialization logs
[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

//Logs printed when SDK OkHttpClient.Builder.build() is called
//(Needs to be called after SDK initialization)
[FT-SDK]AutoTrack   com.ft  D  trackOkHttpBuilder

If the initialization call order cannot be adjusted, you can choose manual integration.

Using Interceptor or EventListener for Secondary Data Processing¶

After Plugin ASM insertion, it adds addInterceptor to the original project code's OkHttpClient.Builder(), adding FTTraceInterceptor and FTResourceInterceptor. These use the http request's body contentLength to participate in unique id calculation. Data from various stages of Resource is contextually linked through this id. Therefore, if the integrator also adds addInterceptor when using Okhttp and performs secondary processing on the data, causing its size to change, it can lead to inconsistent id calculation across stages, resulting in data loss.

Solution:

ft-sdk < 1.4.1

Resolve this by customizing the order of addInterceptor placement, allowing the SDK method to calculate the id first. To avoid duplicate settings, the custom method requires turning off FTRUMConfig's enableTraceUserResource and FTTraceConfig's enableAutoTrace configurations.

ft-sdk >= 1.4.1

In non-manual setup scenarios, the SDK adapts to this issue automatically. If manual setup has been performed, ensure the Interceptor is placed in a forward position.

OKhttp 3.12.+ Compatibility Issue¶

ft-sdk < 1.6.13 If the Interceptor used reads the response body content for read operations, it may cause the current Resource data to fail to be collected.

Solution:

ft-sdk < 1.6.13

Without changing the Okhttp version, perform manual setup to resolve this issue.

OkHttpClient.Builder builder = new OkHttpClient.Builder()
    .addInterceptor(new CustomReadReponseInterceptor())//Reads response body
    .addInterceptor(new FTTraceInterceptor())
    .addInterceptor(new FTResourceInterceptor())
    .addInterceptor(new CustomRequestBodyFixInterceptor())//Has encryption or modifies body
    .eventListenerFactory(new FTResourceEventListener.FTFactory());

OkHttpClient client = builder.build();

Upgrading Okhttp to version 4.5.0 or above can also resolve this issue.

ft-sdk >= 1.6.13

In non-manual setup scenarios, the SDK adapts to this issue automatically.

Error Data Loss Crash Type Data¶

Confirm if other third-party SDKs with Crash capture functionality are used simultaneously. If yes, place the SDK initialization method after other SDKs.

Missing Specific Field Information in Data¶

User Data Fields¶

Confirm that the user data binding method is called correctly. In debug mode, you can track this issue via logs.

[FT-SDK]FTRUMConfigManager com.demo D  bindUserData xxxx

///---> Your data operations <-----

[FT-SDK]FTRUMConfigManager com.demo D unbindUserData

Missing Custom Parameters or Incorrect Values¶

Confirm it is called in the correct scenario. FTRUMConfig.addGlobalContext and FTLoggerConfig.addGlobalContext are suitable for data that does not change within an application lifecycle, such as application channel, application Flavor attributes, etc. If dynamic scenarios require real-time response, use the manual RUM and Log interfaces.
In debug mode, check the [FT-SDK]SyncTaskManager logs. You can use these logs to verify the correctness of custom field parameters.

Lagging Issue When enableConsoleLog is Enabled¶

If lagging occurs, it might be due to excessively large log collection data. The principle of FTLoggerConfig.enableConsoleLog is to capture android.util.Log, Java, and Kotlin println. It is recommended to adjust the FTLoggerConfig configuration parameters such as sampleRate, logPrefix, and logLevelFilters as needed to eliminate or mitigate this issue.

Okhttp EventListener Fails After SDK Integration¶

After Plugin AOP ASM insertion, eventListenerFactory is added to the original project code's OkHttpClient.Builder(), which will override the original eventListener or eventListenerFactory.

Solution:

ft-sdk < 1.4.1

Turn off automatic Plugin AOP setup FTRUMConfig setEnableTraceUserResource(false), and customize a CustomEventListenerFactory that inherits FTResourceEventListener.FTFactory. Use custom integration.

ft-sdk >= 1.4.1

Customize a CustomEventListenerFactory that inherits FTResourceEventListener.FTFactory. Customize the ASM-written eventListenerFactory by setting FTRUMConfig.setOkHttpEventListenerHandler.

ft-sdk >= 1.6.7

In non-manual setup scenarios, the SDK adapts to this issue automatically.

TraceID Missing or Not Corresponding with Trace Propagation Header¶

When performing complete request data collection, information typically needs to be obtained from both Interceptor and EventListener. To effectively correlate these two parts of data, the SDK needs to rely on a unique ID to link the same network request. However, prior to version 1.6.10, this ID was the same for identical requests, which could lead to data confusion or loss in high-concurrency scenarios. Starting from version 1.6.10, you can call FTSDKConfig.setEnableOkhttpRequestTag(true) or explicitly add a ResourceID to the Request to distinguish unique identifiers for each request, thereby avoiding interference between identical requests. For setup instructions, refer to here.