Troubleshooting

Here are some common issues you might encounter when integrating the Mapp Intelligence React Native SDK, along with suggested solutions:

Issue 1: CocoaPods Installation Failure on iOS

Problem: Running pod install fails with an error, preventing the installation of necessary iOS dependencies.

Solution:

1. Ensure that CocoaPods is installed correctly by running sudo gem install cocoapods. If your project manages CocoaPods with Bundler, use bundle exec pod install.

2. Try clearing the CocoaPods cache by running pod cache clean --all.

3. Delete the Podfile.lock and Pods/ directory from your iOS project and run pod install again.

4. Check that your iOS deployment target is at least 15.1 and that you use Xcode 16.1 or later.

Issue 2: Android Build Fails with SDK or Kotlin Errors

Problem: The Android build fails with SDK compatibility errors, or with Kotlin metadata errors such as an incompatible Kotlin version.

Solution:

1. Check the root android/build.gradle: minSdkVersion must be at least 24, compileSdkVersion and targetSdkVersion at least 36.

2. Make sure the app uses a Kotlin 2.3 compiler. React Native's default Kotlin version is too old for the Mapp Android SDK.

3. Ensure that your JDK version is 21.

4. If you use a custom Gradle setup, make sure it provides the com.android.library, org.jetbrains.kotlin.android, and com.facebook.react plugins.

5. If you recently updated the SDK, clean your project by running ./gradlew clean and rebuild.

Issue 3: Initialization Fails with Network Errors

Problem: The SDK fails to initialize due to network issues, such as an inability to reach the tracking domain.

Solution:

1. Verify that the TRACK_DOMAIN URL is correct and accessible from your development environment.

2. Check your network connection and any firewall settings that might block outgoing requests.

3. Ensure that the app has the necessary permissions to access the internet on both Android and iOS platforms.

Issue 4: Data Not Appearing in Mapp

Problem: Tracking data does not appear in Mapp Intelligence.

Solution:

1. Ensure that the TRACK_IDS and TRACK_DOMAIN are correctly configured during initialization.

2. Check if tracking requests are being sent by inspecting network logs or using a debugging proxy.

3. Verify that the initWithConfiguration method has been called successfully and that isInitialized() returns true.

4. Be aware that data updates in Mapp Intelligence occur on an hourly basis. This means that there may be a delay of up to one hour before newly tracked data appears in the dashboard. If data is not visible immediately, please allow some time before checking again.

Issue 5: Changes Not Applied After Upgrading

Problem: After upgrading the SDK, the app still behaves like the old version, or the native module cannot be found.

Solution: A Metro reload does not update native code. Reinstall the iOS pods, then rebuild and reinstall both native apps. In Expo apps, run npx expo prebuild --clean before rebuilding the development build.

Issue 6: SDK Does Not Work in Expo Go

Problem: The app runs in Expo Go, but the SDK does not load or tracking calls fail.

Solution: Expo Go is not supported, because the SDK contains native code. Create a development build with expo-dev-client and open that app instead. See Expo Integration Guide.

Issue 7: Expo Prebuild Fails with a Groovy Error

Problem: npx expo prebuild stops with the message that the Mapp Expo integration requires a Groovy root build.gradle.

Solution: The config plugin only supports a Groovy root build.gradle, which is the Expo default. If your project uses a Kotlin DSL build script, configure the Kotlin Gradle plugin version in that script yourself.