Skip to content

Troubleshooting

SDK Initialization Exception Check

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

14:46:04.825 [FT-SDK] com.demo E Please install the SDK first (call FTSdk.install(FTSDKConfig ftSdkConfig) when the application starts)

In the Debug environment, after you configure the Guance SDK and run the application for the first time, please check your debugger console in Xcode. The SDK uses assertions to check the correctness of multiple configurations and will crash and output relevant warnings if the configuration is incorrect.

eg: When configuring the SDK, if the datakit metrics write address is not set, the program will crash and output a warning ⚠️ in the console.

*** Assertion failure in +[FTMobileAgent startWithConfigOptions:], FTMobileAgent.m:53
*** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'Please set the datakit metrics write address'

Enable Debug Mode

You can enable the SDK's debug function through the following configuration.

 let config: FTMobileConfig = {
    serverUrl: Config.SERVER_URL,
    debug: true
 };
 FTMobileReactNative.sdkConfig(config);

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

Check Logcat logs with Tag prefixed with [FT-SDK].

The SDK's debug logs are prefixed with [FTLog].

  • When running with xcode, you can directly view the SDK's debug logs in the xcode debug console.

  • When running with terminal commands yarn ios or yarn react-native run-ios, you can view the SDK debug logs in the "Console" on your Mac.

Using the "Console":

Select Action, check Include Info Messages, Include Debug Messages.

Select the debugging device, click the Start button, and enter the search condition [FTLog] in the search condition box on the right. You can then view the SDK's debug logs.

console_app_use

Android Logcat and iOS Xcode Console log examples.

SDK Runs Normally But No Data

  • Check Datakit to see if it is running normally.

  • Confirm that the SDK upload address datakitUrl or datawayUrl is configured correctly and initialized correctly. In debug mode, check the sync logs in Android Logcat or iOS Xcode Console.

  • Check if datakit is uploading data to the corresponding workspace and if it is offline. This can be confirmed by logging into Guance and checking the "Infrastructure".

Data Loss

Partial Data Loss

  • If some data from a RUM Session or a few pieces of data from Log or Trace are lost, first exclude whether sampleRate < 1 is set in FTRUMConfig, FTLoggerConfig, or FTTraceConfig.

  • Incomplete RUM data collection, missing Resource or Action data?

    Resource and Action data are bound to Views. Ensure there is an FTReactNativeRUM.startView operation. Refer to the RUM View documentation to implement View event collection.

  • Investigate network issues on the device uploading data and network/load issues on the device where datakit is installed.

Compatibility Issues

react-native-navigation Runtime Compatibility Issue

ReactTextShadowNode.UNSET Symbol Not Found

This is caused by a react-native-navigation version compatibility issue. Related issue can be viewed here. Fix this issue by modifying or downloading and replacing ReactTypefaceUtils.java.

Module react/jsx-runtime Not Found

Affected scope: SDK version 0.3.0 && React version < 16.14.0

Reason: The SDK internally uses react/jsx-runtime, which is only supported in React >= 16.14.0.

Fix suggestions:

  • Upgrade SDK version to >= 0.3.1

Note: It is not recommended to add the @cloudcare/react-native-mobile dependency library via local path, as it may prevent the error from being fixed.

Native and React Native Hybrid Development

Error: Cannot read properties of undefined (reading 'addError')

Reason: RN SDK version is incompatible with Native SDK version or installation is incomplete.

Problem verification method:

In the Android project root directory, execute the command ./gradlew app:dependencies in the terminal, and check if the output contains cloudcare_react-native-mobile.

cloudcare_react-native-mobile is the dependency library installed on the Android side after adding the Guance RN SDK dependency to the RN project.

Check the Podfile.lock file to confirm if the FTMobileReactNativeSDK dependency exists.

FTMobileReactNativeSDK is the dependency library installed on the iOS side after integrating the Guance RN SDK into the RN project.

Fix suggestions:

  1. Version Compatibility Check

    • Ensure RN SDK and native SDK versions are compatible.
    • View the corresponding native SDK version information for the RN SDK at:

    node_modules/@cloudcare/react-native-mobile/android/build.gradle

    node_modules/@cloudcare/react-native-mobile/FTMobileReactNativeSDK.podspec

  2. Reinstall Dependencies

    • Clean project cache:
    # Clear npm cache
npm cache clean --force
# Or clear yarn cache
yarn cache clean
    • Reinstall dependencies:
    # Using npm
npm install
# Or using yarn
yarn install
# For iOS project, enter the ios directory and execute
pod install

Following the above steps can effectively resolve this error caused by version incompatibility or incomplete installation.

More Related Content

Feedback

Is this page helpful? ×