Troubleshooting¶
SDK Initialization Exception Verification¶
Check Logcat
to confirm if there are logs with Level
as Error
and Tag
prefixed with [FT-SDK]
.
In the Debug environment, after configuring the Guance SDK and running the application for the first time, check your debugger console in Xcode. The SDK will use assertions to verify 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.
Enable Debug Mode¶
You can enable the debug function of the SDK 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
for 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 the terminal command
yarn ios
oryarn react-native run-ios
, you can view the SDK debug logs in the "Console" on the mac.
How to use the "Console":
Select Actions
and check Include Brief Information
and Include Debug Information
.
Select the device to debug, click the Start
button, and enter the search condition [FTLog] in the search condition box on the right. At this point, you can view the SDK's debug logs.
Android Logcat and iOS Xcode Console log examples
SDK Running Normally but No Data¶
-
Check if Datakit is running normally.
-
Confirm that the SDK upload address
datakitUrl
ordatawayUrl
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 Session data or Log, Trace data is lost, first exclude whether
sampleRate < 1
is set in FTRUMConfig, FTLoggerConfig, FTTraceConfig. -
Incomplete RUM data, missing Resource or Action data?
Resource and Action data are bound to View. Ensure that there is a
FTReactNativeRUM.startView
operation. Refer to the RUM-View documentation to implement View event collection. -
Check the network of the device uploading data and the network and load of 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 found here. Fix this issue by changing 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 supported in React >= 16.14.0.
Fix Recommendation:
- Upgrade SDK version >= 0.3.1
Note: It is not recommended to add @cloudcare/react-native-mobile
dependency library using local path, as it may cause errors that cannot be 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 the 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 in 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 in the RN project.
Fix Recommendation:
-
Version Compatibility Check
- Ensure RN SDK and Native SDK versions match.
- View the corresponding Native SDK version information for RN SDK:
node_modules/@cloudcare/react-native-mobile/android/build.gradle
node_modules/@cloudcare/react-native-mobile/FTMobileReactNativeSDK.podspec
-
Reinstall Dependencies
- Clean project cache:
- Reinstall dependencies:
By following the above steps, you can effectively resolve this error caused by version incompatibility or incomplete installation.