Migrating from 1.1.3 to 2.0.0

This guide covers the upgrade from version 1.1.3 to 2.0.0 of the Mapp Intelligence React Native SDK. Choose the path that matches your app:

• Path A: Keep using a React Native CLI app.

• Path B: Add the SDK to an existing Expo SDK 56 app.

• Path C: Convert a React Native CLI app to Expo Prebuild.

Is this a breaking change?

No. Version 2.0.0 is a major version because the Android build setup changed and Expo support was added. The JavaScript and TypeScript API did not change. Existing imports, initialization, configuration, and tracking calls keep working. The package name and autolinking behavior are unchanged.

What changed is how the SDK builds on Android. Version 1.1.3 shipped its own pinned versions of the React Native Android dependency, the Android Gradle Plugin, and the Kotlin plugin. Version 2.0.0 removes these pins and uses the versions your app already provides. This makes the SDK work in both React Native CLI and Expo-generated projects.

The supported React Native range is wider:

What the SDK handles for you

Note

If your CLI app already builds with version 1.1.3, you do not need a Kotlin migration. Version 1.1.3 already required a Kotlin 2.3 compiler. Keep your current Kotlin and Android SDK values.

Path A: Stay on React Native CLI

You do not need to install Expo, add a config plugin, or change your tracking code.

Step 1: Upgrade the package

npm install mapp-intelligence-reactnative-plugin@2.0.0

With Yarn, run yarn add mapp-intelligence-reactnative-plugin@2.0.0.

Step 2: Check the Android configuration

Your app must use Android min SDK 24 or later, compile SDK 36 or later, and a Kotlin 2.3 compiler. The validated CLI setup uses Kotlin 2.3.21, Gradle 9.0, and Java 21. In a standard root android/build.gradle, these values look like this:

buildscript {
    ext {
        minSdkVersion = 24
        compileSdkVersion = 36
        targetSdkVersion = 36
        kotlinVersion = "2.3.21"
    }

    repositories {
        google()
        mavenCentral()
    }

    dependencies {
        classpath("com.android.tools.build:gradle")
        classpath("com.facebook.react:react-native-gradle-plugin")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlinVersion}")
    }
}

apply plugin: "com.facebook.react.rootproject"

Keep the Android Gradle Plugin and Gradle wrapper versions that come with your React Native version. If your app already uses compatible values, no change is needed.

Step 3: Check custom Gradle setups

The SDK applies the following Gradle plugins but no longer downloads its own versions of them:

• com.android.library

• org.jetbrains.kotlin.android

• com.facebook.react

Standard React Native projects already provide them. If you use a custom root Gradle setup, declare them with versions that match your React Native release. Do not add a versioned com.facebook.react:react-android dependency for the SDK.

Step 4: Reinstall iOS pods

cd ios
pod install
cd ..

If you manage CocoaPods with Bundler, run bundle exec pod install. The iOS deployment target is 15.1, and React Native 0.84 and 0.85 require Xcode 16.1 or later.

Step 5: Clean and rebuild

cd android
./gradlew clean
cd ..
npx react-native run-android
npx react-native run-ios

Warning

A Metro reload is not enough. The SDK contains native code, so you must rebuild and reinstall both apps.

Step 6: Verify

const initialized = await MappIntelligencePlugin.isInitialized();

if (!initialized) {
  throw new Error('Mapp Intelligence did not initialize');
}

await MappIntelligencePlugin.trackPage('Migration verification');

Path B: Add the SDK to an existing Expo app

This path applies if your app already uses Expo SDK 56 with a React Native version in the supported range. Follow the Expo Integration Guide. Your existing initialization and tracking code works unchanged in the Expo development build.

Path C: Convert a CLI app to Expo Prebuild

Converting an app to Expo Prebuild is a bigger change than upgrading the SDK. A clean prebuild regenerates the complete android and ios folders, so you must move existing native customizations into Expo configuration first.

Step 1: Choose a supported version pair

The validated target is Expo SDK 56.0.0 with React Native 0.85.3 and React 19.2.3. Do not migrate to a React Native version outside >=0.84.0 <0.86.0. Follow Expo's Adopt Prebuild guide for the native changes your Expo SDK version needs.

Step 2: Preserve existing native settings

Before the first clean prebuild, list all changes stored in these places:

• Android manifests, resources, Gradle files, and application classes

• iOS Info.plist, entitlements, capabilities, build settings, and AppDelegate

• Push notifications, deep links, URL schemes, background modes, and permissions

• Native files required by other SDKs

Move these settings into app.json, app.config.js, app.config.ts, or app-level config plugins. The Mapp Intelligence config plugin only handles its own Kotlin setting. It cannot preserve other native changes.

Step 3: Adopt Expo modules

After aligning your app with React Native 0.85.3, run Expo's installer and check the result:

npx install-expo-modules@latest
npx expo-doctor

When you adopt full Prebuild, switch your entry point to Expo's registerRootComponent:

import { registerRootComponent } from 'expo';
import App from './src/App';

registerRootComponent(App);

Step 4: Set up the SDK and build

Commit your working CLI project or use a separate branch, so you can compare native behavior later. Then follow steps 1 to 5 of the Expo Integration Guide. Test your app's existing native features as well as Mapp Intelligence tracking.

Using Expo tools without Prebuild

You can install Expo modules in a CLI app and keep maintaining the android and ios folders yourself. In that case, follow Path A. The config plugin has no effect, because config plugins only run during Expo Prebuild. A development build is still required.

Checklist

Staying on React Native CLI

• React Native is within >=0.84.0 <0.86.0.

• React satisfies ^19.2.3.

• Android uses min SDK 24 or later, compile SDK 36 or later, and Kotlin 2.3.

• A custom Gradle setup provides the standard React Native build plugins.

• CocoaPods were reinstalled.

• Both apps were rebuilt and reinstalled.

• isInitialized() and a tracking call succeed.

Moving to Expo Prebuild

• Expo SDK and React Native versions are compatible. The validated pair is Expo SDK 56 with React Native 0.85.3.

• Existing native customizations are in Expo configuration or config plugins.

• expo-dev-client and the SDK are installed.

• mapp-intelligence-reactnative-plugin is in the Expo plugins array.

• npx expo config --type public resolves.

• Repeated clean prebuilds produce the same native projects.

• Android and iOS development apps build and install.

• isInitialized() and a tracking call succeed.

• Testing uses the development app, not Expo Go.